IDS documentation, testcases, and sample IDS / model

Documentation/README.md

@@ -0,0 +1,37 @@
+# Information Delivery Specifications
+
+![IDS Logo](ids-logo.png)
+
+**Information Delivery Specifications (IDS)** is a buildingSMART standard for specifying and checking simple information requirements from IFC models. It is designed as a free, lightweight, standardised approach to model checking.
+
+## Introduction
+
+An IDS is a file format ending in `.ids` containing a list of information **Specifications**. For example, a single **Specification** might say that "_all walls must have a fire rating property_". Model authors receiving an IDS file can use it to ensure all required information is provided for each **Specification**. Model recipients may use the IDS file to check whether the IFC model meets all of the **Specifications**. Reports may also be generated to list the results of **Specification** compliance checks.
+
+![IDS Diagram](ids-diagram.png)
+
+IDS file creation tools and model checking tools are provided by many [software vendors](https://technical.buildingsmart.org/resources/software-implementations/). You can write your own customised IDS **Specifications** from scratch or start from a [public IDS template](todo). Any IFC model produced from any software can be checked by an IDS file.
+
+## Beginners tutorial
+
+ 1. [Download and install your favourite software](https://technical.buildingsmart.org/resources/software-implementations/) that supports IDS from the software vendors directory. There is software available for Windows, Mac, and Linux.
+ 2. [Download a sample IDS file](library/sample.ids). This IDS file has two **Specifications**. The first specifies that _the project name should be TEST_. The second specifies that _all walls must have a fire rating property_.
+ 3. [Download a sample IFC model to check](library/sample.ifc). This IFC model has "TEST" as the project name, which satisfies the first **Specification**. However, some walls have a fire rating property, and others do not.
+ 4. Load both the IDS and the IFC in your software, and begin the checking process.
+
+That's it! You may also find more sample IDS templates in the [buildingSMART IDS Template Directory](todo) and more sample IFC models in the [buildingSMART IFC model directory](todo).
+
+If you need help, please feel free to ask for help on the [buildingSMART Forums](https://forums.buildingsmart.org/).
+
+## Begin learning about IDS
+
+ 1. [How does a **Specification** work?](specifications.md)
+ 1. [Guidelines on specifying good **Specification** metadata](ids-metadata.md)
+ 1. [Learn how to specify **Complex Restrictions**](restrictions.md)
+ 1. [Learn how to use the **Entity Facet**](entity-facet.md)
+ 1. [Learn how to use the **Attribute Facet**](attribute-facet.md)
+ 1. [Learn how to use the **Classification Facet**](classification-facet.md)
+ 1. [Learn how to use the **Property Facet**](todo)
+ 1. [Learn how to use the **Material Facet**](material-facet.md)
+ 1. [Learn how to use the **Parts Facet**](todo)
+ 1. [Are you a software developer? Read the developer guide!](developer-guide.md)

Documentation/attribute-facet.md

@@ -0,0 +1,42 @@
+# Attribute facet
+
+Every entity in an IFC model has a list of standardised **Atributes**. **Attributes** are a limited set of fundamental data (usually less than 10) associated with all IFC entities. These are fixed by the IFC standard and cannot be customised.
+
+Here are some common attributes and what they mean:
+
+ - **GlobalId**: a unique ID for the element useful for computer geeks
+ - **Name**: a short name, code, number, or label to identify the object for a human. If you had to annotate the object on a drawing or a schedule, the Name is what you should see. For example, a pump Name might be P-10-A.
+ - **Description**: typically the longer form of the name, written to be descriptive and readable for humans. For example a pump Description might be Water Suction Pump.
+ - **Tag**: this is an ID that may link it back to another BIM application. For example if the IFC model was produced using Revit or ArchiCAD, it might hold the Revit or ArchiCAD element ID.
+
+Information that is not critical to the definition of the IFC entity is stored as a **Property**, not an **Attribute**. For more information view the documentation on the [**Property Facet**](property-facet.md).
+
+For this reason, **Attributes** are a good way to specify an **Applicability** to specific elements, or specify a **Requirement** that certain elements shall be identified, named, or described in a particular way.
+
+To see what **Attributes** are available for an IFC class and what their potential values may be, you will need to check the IFC documentation. Here is how you might find a list of valid **Attributes** for the IFC4X3 schema. The instructions will be similar for all IFC versions.
+
+ 1. Browse to the documentation page for the IFC class you are specifying. For example, [this is the IfcWall documentation page](http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWall.htm).
+ 2. Scroll down to the **Attributes** section of the documentation. Note that by default, not all attributes are shown. Press "_Click to show hidden inherited attributes_" to show all attributes. For IFC4, click on the "_Attribute inheritance_" text header to toggle a table for all attributes.
+ 3. The **Attributes** table will show the **Name** of each **Attribute**. Note that **Attributes** which do not have a number next to them and are in italics are not allowed to be specified. Only enumerated **Attributes** may be specified. For example, you may specify the **Name** attribute for an IfcWall, but you may not specify **ConnectedTo**.
+
+Instead of checking the documentation, your IDS authoring software may help you to shortlist valid **Attributes**.
+
+Following naming conventions and accurately describing elements are critical to many usecases in the AECO industry. For this reason, it is very common to use the **Attribute Facet** in both the **Applicability** and **Requirements** section of **Specifications**.
+
+## Parameters
+
+Parameter | Required | Restrictions Allowed | Allowed Values | Meaning
+--- | --- | --- | --- | ---
+**Name** | ✔️ | ✔️ | A valid attribute name from the IFC schema. | The attribute must exist and have a non-empty value.
+**Value** | ❌ | ✔️ | Any value appropriate to the data type of the attribute | The value of the attribute must match exactly. To specify numbers, you must use a dot as the decimal separator, and not use a thousands separator (e.g. `4.2` is valid, but `1.234,5` is invalid). Scientific notation is allowed (e.g. `1e3` to represent `1000`). To specify true or false, you must specify `TRUE` or `FALSE` as uppercase characters.
+
+## Examples
+
+Applicability Intention | Requirement Intention | Facet Definition
+--- | --- | ---
+Any entity with a Name of "ABC123" | The entity (e.g. Project) must be named "ABC123" | Name="Name", value="ABC123"
+Any entity (but typically IfcMapConversion) with an Easting of 312345 | The entity (e.g. IfcMapConversion) must be geolocated such that the origin is at the Easting of 312345 | Name="Easting", value="312345"
+Any entity with a name starting with "WT" followed by 2 digits, such as WT01, WT02, etc. | The element must have the naming scheme of WT01, WT02, etc | Name="Name", Value="WT[0-9]{2}"
+Any entity with a non-empty Description | The entity must have a description | Name="Description"
+Any entity (typically an IfcTask) with a Status set to either "NOTSTARTED", "STARTED", or "COMPLETED" | The entity Status (e.g. for an IfcTask) must be filled out with either "NOTSTARTED", "STARTED", or "COMPLETED" | Name="Status", Value=["NOTSTARTED", "STARTED", "COMPLETED"]
+Any entity (typically an IfcTaskTime) with a DurationType set to WORKTIME (i.e. based on a calendar) | The duration type (e.g. for an IfcTaskTime) must be based on a calendar, not elapsed time | Name="DurationType", Value="WORKTIME"

Documentation/classification-facet.md

@@ -0,0 +1,28 @@
+# Classification facet
+
+A **Classification System** is a defined hierarchy to categorise elements. An example popular **System** is "Uniclass 2015". Within a **System**, there is a hierarchy of short **Reference** codes that categorise elements in increasing levels of specificity, such as "EF_25_10" and "EF_25_10_25". Any object in IFC model can have a **Classification Reference**.
+
+The **Classification Facet** is different to the **Entity Facet**. The **Entity Facet** is restricted to built-in IFC classes and predefined types, which may also function as a method of **Classification**. In contrast, a **System** specified in the **Classification Facet** refers to a third party, non-IFC **System**.
+
+IFC models keep track of **Classification** names, dates, versions, and other data to uniquely identify the **System**, and may even store the hierarchy of **References**. For this reason, **Classification** requirements should use the **Classification Facet**, as opposed to the **Property Facet**.
+
+**Classifications** are a great way to identify **Applicable** entities, or **Require** that entities should follow a nominated **Classification** system by a workflow, such as in an asset management system, work breakdown structure, or coordination requirement.
+
+## Parameters
+
+Parameter | Required | Restrictions Allowed | Allowed Values | Meaning
+--- | --- | --- | --- | ---
+**System** | ❌ | ✔️ | The name of the **Classification System** | The element must be classified with a reference that is part of a classification system with this name
+**Value** | ❌ | ✔️ | The value of a **Refeference** code in the **Classification System** | The element must be classified with a **Reference** which has a code that matches this value. The value is typically a short code with a separating character that denotes the level of classification
+
+If no parameters are specified, then it means that any **Classification** should be present, regardless of **System** name or **Reference** code.
+
+## Examples
+
+Applicability Intention | Requirement Intention | Facet Definition
+--- | --- | ---
+Any classified element | The entity must be classified | No parameters
+Any entity classified using OmniClass | The entity must be classified using OmniClass | System="OmniClass"
+Any entity classified with either OmniClass or Uniclass 2015 | The entity must be classified using either OmniClass or Uniclass 2015 | System=["OmniClass", "Uniclass 2015"]
+Any entity with a classification reference of "EF_25_10_25" | The element (e.g. a wall) must be classified using the reference "EF_25_10_25" | Value="EF_25_10_25"
+Any element with a Uniclass 2015 classification reference starting with EF_25_10 | The entity (e.g. a wall) must use Uniclass 2015 and have are reference starting with EF_25_10 | System="Uniclass 2015", Value="EF_25_10.*"

Documentation/developer-guide.md

@@ -0,0 +1,70 @@
+# Developer guide
+
+**Warning: IDS is not yet formally released.**
+
+An IDS file is simply an XML file, with its schema defined in XSD. You may open any existing IDS file and inspect its contents to get a feel for how an IDS is structured.
+
+An IDS is considered valid if it passes the XSD-based validation check. All sample IDS files available in the buildingSMART directory of public IDS templates are guaranteed to be valid.
+
+ - [Download the latest IDS v0.6 XSD schema](https://github.com/buildingSMART/IDS/blob/master/Development/0.6/ids_06.xsd)
+ - [Download sample IDS files from the directory of public IDS templates](todo)
+
+There are many freely available online tools and programming libraries that can perform XSD validation. Here is [one such XSD validation tool](https://www.liquid-technologies.com/online-xsd-validator) to save you an online search.
+
+## Authoring IDS
+
+If you are writing software to read and author IDS files only, you **must** meet the following criteria:
+
+ - All IDS software must read and write valid IDS files only.
+ - No proprietary extensions are allowed. If auxiliary systems (e.g. additional loaded metadata) are used to augment IDS or the correlating IFC model, they should be made clear to the user that it is external to IDS.
+ - No data loss shall occur. Loading an IDS and saving the IDS shall preserve all of its information. Minor syntax formatting changes are allowed, so long as the data remains unchanged.
+ - Your software should pass all test cases in the [Authoring Testcases](todo) document.
+
+In addition, it is highly recommended to also provide the following features for users:
+
+ - When users write an IFC class in an **Entity Facet**, your interface should restrict allowable values to valid IFC class names in the selected IFC schema for the specification. Autocompletion is recommended.
+ - When users write a predefined type in an **Entity Facet**, your interface should recommend allowable values based on the nominated IFC class. However, it should still allow users to write a custom predefined type. Autocompletion is recommended.
+ - When users have already specified an **Entity Facet** and are creating an **Attribute Facet**, your interface should restrict allowable values based on the nominated IFC class. Your interface should also guide the user to use the right data type based on the nominated attribute name.
+ - When users have already specified an **Entity Facet** and are creating a **Property Facet**, your interface should recommend allowable property sets based on the nominated IFC class and predefined type. However, it should also allow users to write a custom property set name. If a standardised (e.g. `Pset_` or `Qto_`) property set is nominated, your interface should restrict the allowable property names and recommend the appropriate data type to be used.
+ - You may also choose to preload standardised classification names for commonly known systems, as well as the classification references to prevent spelling errors. You may choose to use this [IFC directory for classification systems](https://github.com/Moult/ifcclassification).
+ - When users are nominating a **Material Facet**, your interface should recommend the IFC recommended material categories (one of 'concrete', 'steel', 'aluminium', 'block', 'brick', 'stone', 'wood', 'glass', 'gypsum', 'plastic', or 'earth')
+
+## Checking IDS against IFC
+
+Any software implementing IDS checking **must** comply with the following test suites.
+
+ - Overall integration testscases (todo)
+ - [Entity testcases](testcases-entity.md)
+ - [Attribute testcases](testcases-attribute.md)
+ - [Classification testcases](testcases-classification.md)
+ - [Property testcases](testcases-property.md)
+ - [Material testcases](testcases-material.md)
+ - [Part testcases](testcases-parts.md)
+
+## Generating reports from IDS results
+
+TODO: specify rules about BCF
+
+## Handling IFC compatibility
+
+If the software is not capable of parsing the specified IFC version nominated by the IDS specification, then the user should be made aware of the limitation.
+
+## Handling different IDS versions
+
+IDS is not yet formally released and so there is no guarantee of vendor support for any IDS version.
+
+## Available developer libraries
+
+To help you get started with development, here is a directory of IDS libraries that you may use in your application. Please feel free to [submit your library](https://github.com/buildingSMART/IDS/pulls).
+
+Language | License | Library
+--- | --- | ---
+C# | ? | [XBim](todo)
+Python | LGPL-3.0-or-later | [IfcOpenShell](todo)
+? | ? | ODA?
+Javascript | ? | Something or other
+
+## More reading
+
+ - [Add your implementation to the software vendors directory](https://technical.buildingsmart.org/resources/software-implementations/)
+ - [Make a suggestion for improvement](https://github.com/buildingSMART/IDS/issues)

Documentation/entity-facet.md

@@ -0,0 +1,44 @@
+# Entity facet
+
+Every entity in an IFC model has an "IFC Class" **Name**. For example, wall entities will have an IFC class of IfcWall, and door entities will have an IFC class of IfcDoor. Entities that don't represent individual building elements will also have a class. For example, the project has a class of IfcProject, window types have a class of IfcWindowType, and cost items have a class of IfcCostItem.
+
+Classes aren’t just for categorising entities. They also indicate what types of properties and relationships it is allowed to have. For example, an IfcWall class can have a fire rating property, but an IfcGrid class cannot.
+
+Different IFC schemas have different IFC classes. More recent IFC schemas contain richer and more diverse IFC classes, which you can compare here:
+
+ - [IFC4X3 list of IFC class names](http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/annex-b1.html)
+ - [IFC4 list of IFC class names](https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/link/alphabeticalorder-entities.htm)
+ - [IFC2X3 list of IFC class names](https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/alphabeticalorder_entities.htm)
+
+Some entities may also optionally have a **Predefined Type**. This is a further level of entity categorisation in addition to the IFC Class **Name**. For example, an IfcWall may have a **Predefined Type** of SHEAR, or PARTITIONING. Whereas the IFC Class **Name** is specified by the IFC standard, the **Predefined Type** may also contain custom values by the user.
+
+The IFC schema documentation contains a list of standard predefined types. Here is how you might find a list of valid **Predefined Types** for the IFC4X3 schema. The instructions will be similar for all IFC versions.
+
+ 1. Browse to the documentation page for the IFC class you are specifying. You can get there from the list of IFC class names above. For example, [this is the IfcWall documentation page](http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWall.htm).
+ 2. Scroll down to the **Attributes** section of the documentation and find the **PredefinedType** attribute.
+ 3. Click on the enumeration link next to the **PredefinedType** attribute to view the list of valid values. For example, for an IfcWall, you will click the link to bring you to [the documentation for IfcWallTypeEnum](http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWallTypeEnum.htm).
+ 4. A list of valid **Predefined Types** are shown in a table.
+
+Choosing from the list of standardised **Predefined Types** is highly recommended. However, if they do not apply to your project you may specify any custom value. For example, you may specify "RADIATIONBARRIER" as a custom **PredefinedType** for an **IfcWall**.
+
+One of the most important aspects of writing a specification is to ensure that it applies to the appropriate IFC class. Typically, every single **Specification** will have an **Entity Facet** used in its **Applicability** section.
+
+## Parameters
+
+Parameter | Required | Restrictions Allowed | Allowed Values | Meaning
+--- | --- | --- | --- | ---
+**Name** | ✔️ | ✔️ | A valid IFC class from the IFC schema. | The IFC Class must match exactly
+**Predefined Type** | ❌ | ✔️ | A valid predefined type from the IFC schema, or any custom text value. | The IFC Predefined Type must match exactly
+
+## Examples
+
+Applicability Intention | Requirement Intention | Facet Definition
+--- | --- | ---
+All partition walls | Must be a partition wall | Name="IFCWALL", PredefinedType="PARTITIONING"
+All floor slabs | Must be a floor slab | Name="IFCSLAB", PredefinedType="FLOOR"
+All door types, such that may be documented in a door types schedule | Must be a door type | Name="IFCDOORTYPE"
+All type elements | Must be a type element | Name="IFC.*TYPE"
+All building storeys | Must be a building storey | Name="IFCBUILDINGSTOREY"
+All related documents, such as drawings, schedules, manuals, and specifications | Must be a document | Name="IFCDOCUMENTINFORMATION"
+All distribution systems, such as hot water systems, electrical circuits, etc | Must be a system | Name="IFCSYSTEM"
+All construction tasks, such as in construction scheduling in a work breakdown structure | Must be a construction task | Name="IFCTASK", PredefinedType="CONSTRUCTION"