search

buildingSMART / IDS

Computer interpretable (XML) standard to define Information Delivery Specifications for BIM (mainly used for IFC)
https://www.buildingsmart.org/standards/bsi-standards/information-delivery-specification-ids/
Other
213 stars 65 forks source link

Specification short code/ identifier #339

Open andyward opened 2 months ago

andyward commented 2 months ago

It seems common when building a set of IDS rules to want provide an identifier or reference for the specification for ease / clarity of identification. e.g. a BEP / EIR might have a table similar to

Reference Rule Name
01.01 a project Name must be defined
01.02 the project Name must match 'Acme Project123'
02.01 a site Name must be defined
02.02 the site Name must match 'Client site'
...
19.16 all doors must have a FireRating property in Pset_DoorCommon with a value being one of '30,60'

...

In each case the numeric Reference is a handy short code for the spec - where the name may be cumbersome to read/scan, or even duplicated. i.e. Rule 19.16 is easier to talk about than _all doors must have a FireRating property in PsetDoorCommon with a value being one of '30,60'. Especially in we change the rule name slightly in future (30,60,90).

Equally Rule 01.02 is more clearly disambiguated from 02.02.

Currently in IDS1.0 a specification has the following attributes:

Question is where would we put this reference today? Possible options include:

  1. In the Identifier - where it's not strictly machine readable / GUID
  2. As part of the Name - where it's purely conventional and hard to work with
  3. In the Description - which rules out using that attribute for it's purpose.
  4. In the Name field - and move the narrative to description - which may cause other UX issues

None feel ideal. I'd like to propose an addition for IDS1.1 of an optional reference which is user-facing 'short code' which could be presented alongside the Name, and used for things like sorting, filtering etc in any user interface.

atomczak commented 1 month ago

The 'Identifier' should be the place for that. Why do you find it 'not strictly machine readable' and how we could improve that in 1.1?

andyward commented 1 month ago

The 'Identifier' should be the place for that. Why do you find it 'not strictly machine readable' and how we could improve that in 1.1?

In the schema annotations there's a note saying This is intended to be a machine readable identifier. - which I interpreted to mean it's more intended to be a Guid (which would not be user facing). I.e. it's more an IfcIdentifier than IfcLabel in IFC terminology.

We don't actually document the identifier attribute in the specification metadata section. Perhaps that's all that's needed in 1.1 is clarification on the purpose of this attribute to remove ambiguity for implementors. My assumption was that identifier would not be presented in any UI by default as it may be used as an opaque key to some external system.

atomczak commented 1 month ago

I see your point now. The identifier is often used as you suggest ('01.02' etc), and it doesn't say what format should be followed. I disagree that it should be hidden from the user; I think it's intended for user input and should be exposed in the interface. @CBenghi, @berlotti?

One problem that it creates is that when a user copy-pastes a specification from one file to the other, the identifier won't necessarily be unique. But the same goes for GUID unless made using uuid3/5 (hashing).

Anyway, I agree that we should explain it better in the docs.

atomczak commented 1 day ago

https://github.com/buildingSMART/IDS/pull/369 resolves it