Generate schema Markdown docs automatically in this repository#94
Open
Generate schema Markdown docs automatically in this repository#94
Conversation
jbrown-xentity
approved these changes
Mar 20, 2026
Collaborator
jbrown-xentity
left a comment
jbrown-xentity
left a comment
There was a problem hiding this comment.
Some general comments, not required to be solved.
We should consider where and how it looks to "release" these as official documents, maybe on resources.data.gov? Or maybe we don't need to release all of them, we just release catalog and dataset (since the sub-fields are documented)?
Comment on lines
+27
to
+29
| - name: Check docs are up-to-date | ||
| working-directory: ./jsonschema | ||
| run: poetry run python generate_schema_docs.py --check |
Collaborator
There was a problem hiding this comment.
Aren't there tools for committing back to the branch for things like this? Could we just run the generate and push back, instead of running the --check?
Comment on lines
+75
to
+107
| ### <a name="restrictionStatus_oneOf_i0"></a>Property `AccessRestriction > restrictionStatus > oneOf > Concept` | ||
|
|
||
| **Title:** Concept | ||
|
|
||
| | | | | ||
| | ------------------------- | ---------------------------------- | | ||
| | **Type** | `object` | | ||
| | **Required** | No | | ||
| | **Additional properties** | Any type allowed | | ||
| | **Defined in** | /dcat-us/3.0.0/definitions/concept | | ||
|
|
||
| **Description:** inline description of restriction status | ||
|
|
||
| | Property | Type | Title/Description | | ||
| | ------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------ | | ||
| | - [@id](#restrictionStatus_oneOf_i0_@id ) | string | - | | ||
| | - [@type](#restrictionStatus_oneOf_i0_@type ) | string | - | | ||
| | - [altLabel](#restrictionStatus_oneOf_i0_altLabel ) | null or string | alternate label | | ||
| | - [altLabelMap](#restrictionStatus_oneOf_i0_altLabelMap ) | null or object | Language map for alternate label. E.g. {'es': 'spanish words', 'fr': 'french words'} | | ||
| | - [definition](#restrictionStatus_oneOf_i0_definition ) | null or string | definition | | ||
| | - [definitionMap](#restrictionStatus_oneOf_i0_definitionMap ) | null or object | Language map for definition. E.g. {'es': 'spanish words', 'fr': 'french words'} | | ||
| | + [inScheme](#restrictionStatus_oneOf_i0_inScheme ) | Combination | in scheme | | ||
| | - [notation](#restrictionStatus_oneOf_i0_notation ) | Combination | notation | | ||
| | + [prefLabel](#restrictionStatus_oneOf_i0_prefLabel ) | string | preferred label | | ||
| | - [prefLabelMap](#restrictionStatus_oneOf_i0_prefLabelMap ) | null or object | Language map for preferred label. E.g. {'es': 'spanish words', 'fr': 'french words'} | | ||
|
|
||
| #### <a name="restrictionStatus_oneOf_i0_@id"></a>Property `AccessRestriction > restrictionStatus > oneOf > Concept > @id` | ||
|
|
||
| | | | | ||
| | ------------ | -------- | | ||
| | **Type** | `string` | | ||
| | **Required** | No | | ||
| | **Format** | `iri` | |
Collaborator
There was a problem hiding this comment.
These are going to get extremely repetitive. In the options, can we link to the class reference instead of inline displaying the options for the class?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
We want to be able to generate documentation automatically that matches the schema we have defined. This is a proof-of-concept that uses a Python library called json-schema-for-humans that can create documentation from the schema files. We use a custom script to handle our multi-file setup and to make the process repeatable for use in CI/CD.
This is a first attempt. The generated markdown is correct and accurate, but not as user-friendly as it could be. The json-schema-for-humans library has numerous customization options and we can even use our own templates entirely as we work to improve the documentation and make it more and more useful for implementers. I anticipate lots of ongoing work to identify issues with the documentation and make incremental improvements.
Typically, we wouldn't include generated files in a Github repository alongside the "source" which in this case are the schema files, but in order to have the documentation close at hand, we are going to do so here. To ensure that the generated documentation doesn't get out of date with the schema as we've defined it, we use a Github Actions job to run our script in
--checkmode where it tests whether the docs it would generate agree with what is in the repository.