Open cmungall opened 5 years ago
Leaving this ticket open for now, as I'm sure there's more documentation to do.
That said, it'd be good to know if we want a Google doc to be the permanent home for this, or do we want to have all of this ultimately reside on the GOC wiki.
Pretty clear to me that you don't want the gdoc to be a final home. That one hasn't been edited in more than a year and is unlikely to match what is now live in the schema. I think there needs to be a way to have legible documentation generated automatically from the schema itself which is the ultimate source of truth here.
Do you have any recommendation of where to look to generate a schema from the Shex ? I suppose we could also ask on the Shex gitter / forum. They may be working on something as it seems a pretty generic use case for them
On Nov 2, 2020, at 2:46 PM, goodb notifications@github.com wrote:
Pretty clear to me that you don't want the gdoc to be a final home. That one hasn't been edited in more than a year and is unlikely to match what is now live in the schema. I think there needs to be a way to have legible documentation generated automatically from the schema itself which is the ultimate source of truth here.
— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub, or unsubscribe.
Not specifically no. That would be a good forum to engage with for this issue. I think it would be pretty easy to write code that could generate a web page or wiki page from a schema. With appropriate inline comments in the schema elements, that would serve the purpose.
Here's an example of some HTML built from some ShExJ: DDI_4-DR0.2 ConceptSystem . The "⇩"s represent EXTENDS clicking them copies the extended shape inline. It uses an experimental namespace (undocumneted) to capture UML annotations and uses https://github.com/commonmark/commonmark.js as a datatype to know to interpret it as markdown.
It's conveniently cut-and-paste-able for email and issues, e.g.:
ConceptSystem ⇩AnnotatedIdentifiable
│ Whether the collection is a bag or a set: a bag is a collection with duplicates allowed, a set is a collection without duplicates.
├▻type CollectionType ?
│ If members are ordered set to true, if unordered set to false.
├▭isOrdered xsd:boolean ?
│ A structure containing specific relationships between members of the collection.
├▻isStructuredBy ⇩Identifiable *
│ │ Provides information on reflexivity, transitivity, and symmetry of relationship using a descriptive term from an ennumeration list. Use if all relations within this relation structure are of the same specification.
│ ├▻hasRelationSpecification RelationSpecification
│ │ Restricted to ConceptRelation. ConceptRelations making up the relation structure.
│ └▻hasMemberRelation *
│ │ Restricts source object to Concept for relationshp
│ ├▻source Concept
│ │ Restricts target object to Concept for relationshp
│ └▻target Concept
│ The conceptual basis for the collection of members.
└▻definingConcept Concept *
but the HTML is unpleasant if the annotations are long (see platformType
in InstanceVariable
) because I never figured out a CSS-only way to create indented vertical lines. I think FHIR does this with bootstrap but the markup is hilariously complex.
If anyone can guide me on the markup, I can update the tool.
https://docs.google.com/document/d/1OsE19zh8KE_2wT3-8oJysqEGqy-fahnhcjthO34IWP4/edit