Fix stale/drifted schema docs and rewrite naming conventions - #30
Merged
mpfl merged 2 commits intoAug 5, 2026
Merged
Conversation
The RST docs and doc/metadata-block-field-naming.md had drifted from the RAiD LinkML model and the actual running service (au-research/raid-au), verified against validator source, config, DB migration history, Jira, and a production data export (Zenodo 10.5281/zenodo.21331421): - contributors.rst: ISNI is live (not "proposed"); noted ORCID Sandbox and the pending local checksum hardening - spatialCoverages.rst: Geonames is live; corrected the OpenStreetMap schemaUri to the actual configured value; removed Marine Regions (descoped) - subjects.rst: added ANZSRC SEO (real seed data since Dec 2025); removed Library of Congress (descoped) - identifier.rst: documented raidAgencyUrl, confirmed mandatory/ system-supplied by its 100% presence in production data - metadata.rst: new page for the previously-undocumented metadata block (created/updated only; raidModelVersion intentionally left out as it's not implemented anywhere yet) - metadata-block-field-naming.md: rewritten to describe the nested dot-path field convention that's actually implemented, replacing a flattened-field-name convention that was never real Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- metadata moved from section 15 to section 2 (right after identifier,
matching its role as a record-level block), cascading a renumber
through every subsequent core and extended section (dates 2->3 ...
traditionalKnowledge 14->15)
- subjects.rst: removed a leftover LoC example under subject.id, and
corrected the ANZSRC FoR example to the real production id format
(linked.data.gov.au/def/anzsrc-for/2020/{code}, verified against
au-research/raid-au's Zenodo data export), rather than the schemaUri's
vocabs.ardc.edu.au/repository/api/lda/... browse URL
- spatialCoverages.rst: replaced three stale nominatim.openstreetmap.org
examples with real, verified www.openstreetmap.org production examples
- alternateUrls.rst: fixed two RST heading underlines left too short by
the 9->10 digit-count change
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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
1 participant
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.
Summary
Re-opened after the first attempt (#29) was accidentally merged into the previous
docs-previewbranch. That branch has been deleted and recreated fresh offmain; this PR targets the new one. Nothing has been merged intomain.Audited
rtd/docs/source/anddoc/metadata-block-field-naming.mdagainst the RAiD LinkML model, the actual running service (au-research/raid-au), and a production data export, since both had drifted from reality over time.contributors.rst: ISNI is live (was marked "proposed, not yet implemented"); noted ORCID Sandbox and the still-pending local checksum hardening (RAID-791)spatialCoverages.rst: Geonames is live; corrected the OpenStreetMap schemaUri and examples to what's actually configured/live; removed Marine Regions (descoped)subjects.rst: added ANZSRC Socio-Economic Objectives (real seed data since Dec 2025); removed Library of Congress (descoped), including a leftover example; corrected the ANZSRC FoR example to the real productionidformatidentifier.rst: documentedraidAgencyUrl, confirmed mandatory/system-supplied (present in 100% of a 575-record production sample)metadata.rst(new page, section 2, right afteridentifier): documents the previously-undocumentedmetadatablock —created/updatedonly;raidModelVersionintentionally left out since nothing implements it yet. Renumbered every subsequent core/extended section accordingly.metadata-block-field-naming.md: rewritten to describe the nested dot-path field convention that's actually implemented (e.g.identifier.schemaUri), replacing a flattened-field-name convention (identifierSchemeUri) that was never realEvery change was verified against validator source, Spring config, DB migration history, relevant Jira tickets, and the ARDC RAiD AU Zenodo data archive (
10.5281/zenodo.21331421) — not just the schema/vocab layer, which turned out to be an unreliable signal on its own in both directions.Test plan
cd rtd/docs && make html)identifier,metadata,contributors,subjects,spatialCoveragespagesmetadata, cascading through the rest) renders correctly and doesn't collide with anything else in the toctree🤖 Generated with Claude Code