Instructions, Annotations, Translations & Co

[hesrah]

We generate IDS files from user models mapped to IFC. In a user model a lot of definitions are possible, such as description for the object class (entity) and attributes. The object class names, attribute names or enumeration values etc. are proper names in the user context language.

Few IDS XML elements have the instructions attribute, so in our IDS export we put a lot of this information in annotations elements. The receiving side could use this information to configure their application (tooltips, label translation etc.). But in the form of annotations elements, the information is unstructured. E.g. the receiving side can’t distinguish between an information describing an object class (entity) and a translation for the object class name.

An IDS example from our export below.

I'm looking for ways IDS can provide more guidance to structure such information. Any ideas or proposals?

<?xml version="1.0" encoding="utf-8"?>
<ids xmlns="http://standards.buildingsmart.org/IDS" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://standards.buildingsmart.org/IDS http://standards.buildingsmart.org/IDS/ids_1_0.xsd">
    <info>
        <title>DBM für Betriebsphase aufbereiten</title>
        <copyright>FHNW</copyright>
        <version>IDS 0.9.3</version>
        <description>DBM für Betriebsphase aufbereiten</description>
        <author>Author sample@sample.ch</author>
        <date>2023-03-13</date>
        <purpose>FDK</purpose>
        <milestone>Projekt abgeschlossen</milestone>
    </info>
    <specifications>
        <specification name="Deckschicht" minOccurs="0" maxOccurs="unbounded" ifcVersion="IFC4">
            <applicability>
                <entity>
                    <name>
                        <xs:annotation>
                            <xs:documentation>Identifkation:	FB-1
Art der Verortung:	Linear, Linie
eBKP-Zuweisung:	Zuweisung offen
LOGO-Klasse:	Schicht</xs:documentation>
                        </xs:annotation>
                        <simpleValue>IFCBUILDINGELEMENTPROXY</simpleValue>
                    </name>
                    <predefinedType>
                        <simpleValue>USERDEFINED</simpleValue>
                    </predefinedType>
                </entity>
            </applicability>
            <requirements>
                <property measure="IfcLabel" minOccurs="1" maxOccurs="unbounded" instructions="Bindemittel">
                    <propertySet>
                        <simpleValue>CHTBAZH_Oberbau</simpleValue>
                    </propertySet>
                    <name>
                        <simpleValue>Bindemitteltyp</simpleValue>
                    </name>
                    <value>
                        <xs:annotation>
                            <xs:documentation>Bindemitteltyp</xs:documentation>
                        </xs:annotation>
                        <xs:restriction base="xs:string">
                            <xs:enumeration value="? Unbekannt">
                                <xs:annotation>
                                    <xs:documentation>? Unbekannt</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 100/150">
                                <xs:annotation>
                                    <xs:documentation>B 100/150</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 120/150">
                                <xs:annotation>
                                    <xs:documentation>B 120/150</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 20/30">
                                <xs:annotation>
                                    <xs:documentation>B 20/30</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 40/50">
                                <xs:annotation>
                                    <xs:documentation>B 40/50</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 50/70">
                                <xs:annotation>
                                    <xs:documentation>B 50/70</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 55/70">
                                <xs:annotation>
                                    <xs:documentation>B 55/70</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 70/100">
                                <xs:annotation>
                                    <xs:documentation>B 70/100</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="B 80/100">
                                <xs:annotation>
                                    <xs:documentation>B 80/100</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="Bitumen">
                                <xs:annotation>
                                    <xs:documentation>Bitumen</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="Emulsion">
                                <xs:annotation>
                                    <xs:documentation>Emulsion</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="HB Hartbitumen">
                                <xs:annotation>
                                    <xs:documentation>HB Hartbitumen</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="hydraulischer Kalk">
                                <xs:annotation>
                                    <xs:documentation>hydraulischer Kalk</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB-E 10/30-70 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB-E 10/30-70 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB-E 30/50-65 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB-E 30/50-65 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB-E 50/70-65 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB-E 50/70-65 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB 10/40 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB 10/40 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB 25/55 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB 25/55 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB 30/50-65 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB 30/50-65 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB 45/80 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB 45/80 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB 65/105 (CH-E)">
                                <xs:annotation>
                                    <xs:documentation>PmB 65/105 (CH-E)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB Polymodifizierte Bindelmittel (alt)">
                                <xs:annotation>
                                    <xs:documentation>PmB Polymodifizierte Bindelmittel (alt)</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="PmB Polymodifizierte Bindemittel">
                                <xs:annotation>
                                    <xs:documentation>PmB Polymodifizierte Bindemittel</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="Spez NV">
                                <xs:annotation>
                                    <xs:documentation>Spez NV</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                            <xs:enumeration value="Zement">
                                <xs:annotation>
                                    <xs:documentation>Zement</xs:documentation>
                                </xs:annotation>
                            </xs:enumeration>
                        </xs:restriction>
                    </value>
                </property>
            </requirements>
        </specification>
    </specifications>
</ids>

[Moult]

I write lengthy descriptions. Does that help?

        <specification name="Building storey information (simplified for Revit)" ifcVersion="IFC4" description="Building storeys must be named consistently throughout all models so that models can be federated and storeys consistently identified. The ability to federate based on storey naming is a requirement for facility management deliverables such as COBie and integration into building management systems." instructions="The architect is responsible for providing storeys and storey names. All other disciplines must follow these names. No fake storeys or storeys for the purposes of modeling software limitations are allowed to be submitted. All drawings, schedules, and other documents must also use these names exactly such that a plaintext search will yield correct results." minOccurs="0" maxOccurs="unbounded">
            <applicability>
                <entity>
                    <name>
                        <simpleValue>IFCBUILDINGSTOREY</simpleValue>
                    </name>
                </entity>
            </applicability>
            <requirements>
                <attribute instructions="Valid examples include G, LG, UG, B01, B02, L01, L02, and L12." minOccurs="1" maxOccurs="1">
                    <name>
                        <simpleValue>Name</simpleValue>
                    </name>
                    <value>
                        <xs:restriction base="xs:string">
                            <xs:pattern value="((B|L)[0-9]{2}|G|LG|UG)" />
                        </xs:restriction>
                    </value>
                </attribute>
                <attribute instructions="Site should be chosen for a level that is used to represent the surrounding site." minOccurs="1" maxOccurs="1">
                    <name>
                        <simpleValue>ObjectType</simpleValue>
                    </name>
                    <value>
                        <xs:restriction base="xs:string">
                            <xs:enumeration value="Site" />
                            <xs:enumeration value="Level" />
                        </xs:restriction>
                    </value>
                </attribute>
                <attribute instructions="The building storey SSL elevation defined in millimeters in AHD. If this value is not present, the correct Z axis placement shall be used." minOccurs="1" maxOccurs="1">
                    <name>
                        <simpleValue>Elevation</simpleValue>
                    </name>
                </attribute>
                <property measure="IfcLengthMeasure" instructions="The storey to storey height in millimeters. Left blank if the level is a site level, or the topmost level (e.g. roof)" minOccurs="1" maxOccurs="1">
                    <propertySet>
                        <simpleValue>Qto_BuildingStoreyBaseQuantities</simpleValue>
                    </propertySet>
                    <name>
                        <simpleValue>GrossHeight</simpleValue>
                    </name>
                </property>
            </requirements>
        </specification>

... rendered like this:

[MatthiasWeise]

We are running into the same question as mentioned by @hesrah.

@Moult The need for further information is not really about explaining what is encoded in the rule. Main requirement from our point of view is coming from:

1. requirements being encoded in other languages like IFC, for example we can check existence of FireRating property, but for communication with end users I would rather use the domain language like the German "Feuerwiderstandsklasse".
2. while a short name might be sufficient in many cases (and best to show in UI of the checking tool), we may also want to give further explanation, in particular if it is a user defined property that is not part of the IFC specification.

Options and consequenses for a solution:

1. go with additional xs:annotation tags, which is proper XML but is not a valid according to the IDS schema definition (see #2929). This option is therefore not really a solution.
2. encode everything into the existing instruction attribute, which requires additional implementer agreements (we may miss instruction attributes, not yet fully sure)
3. extension of the schema.

Who else is running into such documentation issues?
Where do we miss such functionality (additional documentation or an instruction attribute)?
In general, I am in favour to keep it simple for IDS 1.0

More feedback is welcome!

[Moult]

for communication with end users I would rather use the domain language like the German "Feuerwiderstandsklasse".

I think we should add this to the recommendation for implementers to simply show the localised version of the property. IFC contains translations of properties, and it would be good incentive for buildingSMART to improve their i18n coverage. This problem is not specific to IDS, it's an overall IFC i18n issue.

we may also want to give further explanation, in particular if it is a user defined property that is not part of the IFC specification.

Sounds exactly like the purpose of the instruction attribute, as shown in my example in the post above.

[MatthiasWeise]

I think we should add this to the recommendation for implementers to simply show the localised version of the property. IFC contains translations of properties, and it would be good incentive for buildingSMART to improve their i18n coverage. This problem is not specific to IDS, it's an overall IFC i18n issue.

I fully agree (should be a must have option in the tools)!
While this is a general recommendation I still see a need to offer more custom specific names and descriptions (also due to the fact that we do not have all translations).

Sounds exactly like the purpose of the instruction attribute, as shown in my example in the post above.

I like the rendering and more user friendly way to show requirements.
Some additional remarks to your example:

• why do we have description and instruction on specification level, what is the difference between both?
• in your example you add information about responsibility to the instructions. If we need such information, for instance to meet with EN-17412, I would rather go with a proper attribute. But that is a different topic. ;-)
• we may also see a need to have specific description/instructions for each enumeration value. In your example you put everything into the instructions of the attribute/property, which I guess is fine for IDS 1.0.

I wonder if we should have name, description and instructions for each requirement as well (similar to specification).

Another alternative of course would be to split your example into one specification for each attribute/property requirement. Definitions with same applicability can then be grouped by the receiving application if needed. Not a very efficient way of exporting our requirements, but in the end very flexible.

[Moult]

why do we have description and instruction on specification level, what is the difference between both?

My interpretation is that the description describes why the specification exists, why it is valuable, why people need it, what usecases it is for, etc ... i.e. it is descriptive. The instruction is instructive, it tells you exactly how you must go about compliance (e.g. who should have authority, who checks it, whether there's a sequence to filling it in, whether you should refer to another data source like a spreadsheet or online resource, etc).

EN-17412

Sure :) I'm not familiar with it, but alignment with standards is generally desirable.

we may also see a need

Key word is "we may". I'd say try to do the best you can with as little as possible, before trying to plan for everything, even if you think it's a must-have right now. I have been running IDSes on many jobs and client requirements for a while now, and haven't really yet been needing extra metadata.

I wonder if we should have name, description and instructions for each requirement as well

After a good half a year of using IDS quite extensively on large commercial projects I don't see the need for it. I'd find it redundant and / or not sure what to fill out a lot of the time. The facet parameters speak for themselves a lot of the time.

Another alternative of course would be to split your example into one specification for each attribute/property requirement.

Yes - this is preferred. I'd say the main goal of IDS isn't about "efficiency of exporting requirements". It's about semantically describing requirements as meaningfully as possible. Even if that means splitting into multiple specs, or even multiple IDSes. I've got IDSes which cover many broad topics like costing, scheduling, sustainability, facility management ... and each one breaks down into many, many specs which are very descriptive. I want somebody to read my IDS without me present and go "oh ok, they want this property and if i don't give it to them, it will impact this process with this trade off (e.g. the costers won't be able to cost steel elements from the model)".

[MatthiasWeise]

My interpretation is that the description describes why the specification exists, why it is valuable, why people need it, what usecases it is for, etc ... i.e. it is descriptive.

I thought that is defined in the meta data of our IDS file, i.e. purpose and milestone. No need to repeat for each element.

The instruction is instructive, it tells you exactly how you must go about compliance (e.g. who should have authority, who checks it, whether there's a sequence to filling it in, whether you should refer to another data source like a spreadsheet or online resource, etc).

Shouldn't that be part of an IDM?

After a good half a year of using IDS quite extensively on large commercial projects I don't see the need for it. I'd find it redundant and / or not sure what to fill out a lot of the time. The facet parameters speak for themselves a lot of the time.

True for English speaking countries. Unless if we have a proper translation in place I would not assume so for other countries.
For me the facet paramters reflect the technical/IFC view on our requirements, whereas name/description/instruction is the human view.

Yes - this is preferred. I'd say the main goal of IDS isn't about "efficiency of exporting requirements". It's about semantically describing requirements as meaningfully as possible. Even if that means splitting into multiple specs, or even multiple IDSes.

I agree. Proper visualization of IDS requirements (meaningfull grouping) then becomes responsibility of importing applications.

[Moult]

I thought that is defined in the meta data of our IDS file, i.e. purpose and milestone. No need to repeat for each element.

The IDS is a group of specifications which share a common purpose to be delivered at a (potentially contractual) milestone.

Each specification may target different sets of requirements.

I believe this is best shown through examples.

[atomczak]

Would instructions on all facets (both in applicability and requirements) help? Does anyone have anything against it? This would also increase the symmetry between facets.