search

BuildingSync / schema

BuildingSync® Schema
https://buildingsync.net
Other
23 stars 22 forks source link

Docs/generic linking elements #415

Closed JieXiong9119 closed 2 years ago

JieXiong9119 commented 2 years ago

Any background context you want to provide?

As pointed out in #295, we need annotations to the linking ID and IDREF elements in BuildingSync Schema to avoid confusion and ambiguity when using ID referencing in creating/editing a BuildingSync xml.

What does this PR do?

This PR creates the initial documentation to clarify the valid linking elements in BuildingSync Schema. See the generated document in \docs\linking_elements.md

What are the relevant tickets?

295

Possible next steps

We will create a follow-up ticket to discuss the standardization of the naming of ID elements. Proposed changes: AlternativeSystemAdded -> AlternativeSystemIDAdded AlternativeSystemReplacement -> AlternativeSystemIDReplacement ExistingScheduleAffected -> ExistingScheduleIDAffected ExistingSystemAffected -> ExistingSystemIDAffected ExistingSystemRemoved -> ExistingSystemIDRemoved ExistingSystemReplaced -> ExistingSystemIDReplaced SourceHeatingPlantID -> HeatingPlantID LinkedHeatingPlantID -> HeatingPlantID DeliveryID -> LinkedDeliveryID MakeupAirSourceID -> MakeupAirSpaceID ModifiedSchedule -> ModifiedScheduleID ModifiedSystem -> ModifiedSystemID ReferenceCase -> ReferenceScenarioID

JieXiong9119 commented 2 years ago

This is great, thanks for thoroughly documenting everything!

I wonder if we should go ahead and update the documentation in the schema itself, For example we could update the documentation for ExistingSystemReplaced here to say something like "ID of any existing systems affected by the measure. It should reference a BuildingSync/Facilities/Facility/Systems/Systems/System"

https://github.com/BuildingSync/schema/blob/7c794396173ee2b16c24b5de7b585bcb318cc5c1/BuildingSync.xsd#L3592

It might be easier to maintain if we put the documentation in the schema, but I'm definitely open to other thoughts! A downside of putting it only in the schema is maybe user accessibility

This is great idea. We can include this change in the renaming PR?

macintoshpie commented 2 years ago

We can include this change in the renaming PR?

Sure that works for me