Better describe the purpose of displayId

[graik]

The current description of displayId (section 7.1 of spec) only states:

The displayId property is an OPTIONAL identifier with a data type of String . This property is intended to be an intermediate between name and identity that is machine-readable, but more human-readable than the full URI of an identity.

(The following statement about displayId being "locally unique" has been challenged (issue #42) and will be removed.)

In section 11.2 (Compliant SBOL objects), point 2 states:

\2. The persistentIdentity and displayId properties are REQUIRED of a compliant SBOL object.

Which makes displayId not quite completely optional. It becomes a bit clearer that displayId is considered the human-readable "subject ID" within the URI of an SBOL object:

\3. The persistentIdentity of a compliant TopLevel object MUST end with a delimiter (’/’, ’#’, or ’:’) followed by the displayId of the object.

Recommended rules 1015 - 1019 reinforce this idea.

However, none of this is obvious from the actual description of displayId. Furthermore, it is difficult to see a clear difference between the name field and displayId. See issue #54 asking to rename displayId.

I suggest to update the spec with a clarification along these lines:

1. displayId is considered an identifier [see: http://purl.org/dc/elements/1.1/identifier], allowing the unambiguous reference to an SBOL object within the context, for example, of a given parts registry.
2. displayId should be human-readable in order to allow users to quickly locate a part in a registry or communicate about it.
3. identity URIs of SBOL objects should use displayId as their subject ID (see section 11.2 and rules 1015 - 1019).
4. The parts IDs given by partsregistry.org (e.g. "BBa_P1010") are a typical example of an displayId in action.

I also suggest to ammend the description of the name field:
By way of example, the name property of a CompoentDefinition could be a gene name or similar "human-understandable" name, usually following some expert convention.

[graik]

Taking away the "Non-SEP change" label because this should really be decided by another pair of eyes.

[cjmyers]

Hi Raik,

Based on our agreement at the workshop, this would not fall into SEP category. This is only some word-smithing, and I think it is perfectly reasonable text to add to 2.0.1. The current draft is here:

https://www.overleaf.com/4622108kcsdyv#/13975227/

Feel free to edit it as you have described. All issues marked 2.0.1 have been handled, but I’m just going through to make sure the validation issues that I raised are indeed implementable in the library. The implementation should be done shortly, and it has already found a few minor typos in the new updated rules.

I hope to finish my pass on 2.0.1 next week, then get it back into the git repository properly and passed back to the editors for review.

Chris

On Mar 19, 2016, at 11:38 AM, Raik Grünberg notifications@github.com wrote:

Taking away the "Non-SEP change" label because this should really be decided by another pair of eyes.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub #55 (comment)

[graik]

OK, re-added Non-SEP flag, and downgraded to 2.0.1 milestone. Not sure when I will get to edit the document but I put it on my to do list.

[jakebeal]

Note: If 2.0.1 is ready to release before you get to it, we can bump it back to 2.1.1, since 2.1.0 is expected to be release shortly after 2.0.1.

[jakebeal]

Bumping to 2.1.1 since this is not yet done, but 2.0.1 is ready for release.