Allowed Values for Topic data and the role of Project Extensions

Open
#376 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Stale
Tech stack
json, xml
Domain
api, documentation

Research direction

Review the allowed-value discussion in section 3.1.4 and Per-Entity Authorization in section 1.2.1, then compare the BCF-XML and BCF-API schemas cited in the issue. Document the intended handling of enforced, mapped, missing, null, and invalid topic values, including whether BCF-API topics remain exportable to BCF-XML.

Written by the indexing model from the issue text.

Description

I'm not sure how to handle Project Extensions for allowed values on topics (3.1.4).

We had some discussions about it in our team but didn't get to a solution as the standard is very vague about what should happen if values are posted to the server that do not appear in the lists of topic_type, topic_status, priority, etc.

Are these lists just non-mandatory suggestions for the user? Or should these be enforced if defined? I think the second option makes more sense, given that the lists can be narrowed down even further by Per-Entity Authorization (1.2.1). (Or could they also be extended by Per-Entity Authorization? Or defined completely different? I don't know.)

In any case, what happens, for example, when one tries to import a BCF-XML file that contains different values? As long as our workflow was solely file-based, we offered a mapping table for such cases. This worked OK. But such a mapping can not currently be shared with a BCF server via a defined BCF-API interface, so every client would do its own mapping.
And it still doesn't answer what should happen with values that do not fit even after the mapping. Should such topics be rejected? Or accepted with offending values changed to defaults? Speaking of which, there doesn't seem to be a possibility to even define default/fallback values. Of course you could always just use null, but is null a valid option if a list of allowed values exists? Would a topic without a Type or Status even be valid? BCF-XML certainly doesn't think so:

<xs:attribute name="TopicType" type="NonEmptyOrBlankString" use="required"/>
<xs:attribute name="TopicStatus" type="NonEmptyOrBlankString" use="required"/>

BCF-API disagrees:

"topic_type": {
    "type": ["string",
    "null"]
},
"topic_status": {
    "type": ["string",
    "null"]
},

Which leads to a bizarre situation: With BCF-API, you can can have topics that do not contain sufficient data to be exportable to BCF-XML. This means no less than BCF 3.0 being incompatible with BCF 3.0. What the hell?

I'd appreciate if you could flesh out the documentation to make the intentions behind these concepts clearer.

Dominant language
No language data
Stars
238
Forks
67
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from buildingSMART/BCF-API

All issues in buildingSMART/BCF-API

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.