DCAT-US3 Review and Guidance

[jbrown-xentity]

Purpose

We want to support DCAT-US3, but we're not sure how to do that.

Given above uncertainty and lack of clarity, conducting research and summarization is needed to provide factual knowledge on future steps.

2 weeks (real time) of effort has been allocated and once compete, findings will be demonstrated and specific future actions will be decided.

Acceptance Criteria

[ACs should be clearly demo-able/verifiable whenever possible. Try specifying them using BDD.]

• GIVEN the DCAT-US3 guidance is officially blessed by OMB
  WHEN 2 weeks expires
  THEN a document containing differences with DCAT-US1.1 is created
  AND future tickets for supporting this standard are created
  AND a review with the team is held.

Background

Published standard: https://infopolicy.github.io/dcat-us/

Sketch

Want to create an itemized list of things that change from 1.1 to 3. Want to also include possible optional differences, such as links to other catalogs, class external references, etc.

[jbrown-xentity]

It's taking a lot to collate this, test various things, and get to the bottom of what this all means.
I've started a document: https://docs.google.com/document/d/1ALjlkNEFyatDA3OQWbw7CiB5exGin6-N-SO42gfG_R4/edit?tab=t.0
I also have a repository that I'm pushing various resources to, such as code, tests, evaluations, diagrams, etc: https://github.com/GSA/dcat-us3-tools/tree/main.

More to come.

[jbrown-xentity]

I've created a lot more tools, and found more issues. The key one is "keyword", this is shortened to just a single string value, and identifier, which is now an array.
The keyword change is important because everyone provides them in an array today, so this is NOT backwards compatible as it stands now. I'm not really sure why that change was made, or if it was an oversight.
The identifier change is important because that is how we distinguish records (and track changes). If additions to that can be made without changing the uniqueness, our entire process for managing harvests needs to be re-considered and thought through.

Another major problem I had was the schema definition itself. It references all these local files, but incorrectly (according to the JSON schema parser I'm using). I tried all kinds of ways to get it to work correctly, and ended up bailing and just building a single schema definitions file that is more correct out of the bundle that was provided. This is now working, and rejecting our example records as expected (because of the keyword issue raised above).

Latest code is pushed up to the repo: https://github.com/GSA/dcat-us3-tools/tree/main.

[jbrown-xentity]

Alright, I've learned much over this last week. For one, I don't think the created JSON Schema was ever intended for use.
For another, I understand more about the SHACL and context definitions that help make clear how this is "backwards compatible", even though it's not.
I've collated my concerns, clear issues, and other items here: https://docs.google.com/document/d/1ALjlkNEFyatDA3OQWbw7CiB5exGin6-N-SO42gfG_R4/edit?tab=t.0#heading=h.2u14859cscyk

Latest code is pushed to the repo: https://github.com/GSA/dcat-us3-tools/tree/main, with updated documentation on usage and state of things.

I'm marking this as ready for review @tdlowden (and @neilmb , if you can spare the brain capacity).

For a final "high level" comparison, you can compare https://github.com/GSA/dcat-us3-tools/blob/main/dcat-us1.1/examples/dcatus.json with the modified version that is DCAT-US3 compatible (with some tweaks to the JSON-LD definition that would need to be published): https://github.com/GSA/dcat-us3-tools/blob/main/dcat-us3/examples/good/dcatus-modified.json

[tdlowden]

Thanks for this! I'm super appreciative of you taking the time to dig in so deep. I made some comments.

…

On Fri, Oct 24, 2025 at 7:30 PM James Brown ***@***.***> wrote: *jbrown-xentity* left a comment (GSA/data.gov#5501) <#5501 (comment)> Alright, I've learned much over this last week. For one, I don't think the created JSON Schema was ever intended for use. For another, I understand more about the SHACL and context definitions that help make clear how this is "backwards compatible", even though it's not. I've collated my concerns, clear issues, and other items here: https://docs.google.com/document/d/1ALjlkNEFyatDA3OQWbw7CiB5exGin6-N-SO42gfG_R4/edit?tab=t.0#heading=h.2u14859cscyk Latest code is pushed to the repo: https://github.com/GSA/dcat-us3-tools/tree/main, with updated documentation on usage and state of things. I'm marking this as ready for review @tdlowden <https://github.com/tdlowden> (and @neilmb <https://github.com/neilmb> , if you can spare the brain capacity). For a final "high level" comparison, you can compare https://github.com/GSA/dcat-us3-tools/blob/main/dcat-us1.1/examples/dcatus.json with the modified version that is DCAT-US3 compatible (with some tweaks to the JSON-LD definition that would need to be published): https://github.com/GSA/dcat-us3-tools/blob/main/dcat-us3/examples/good/dcatus-modified.json — Reply to this email directly, view it on GitHub <#5501 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABSAZWHZSUB43PJKKJ6Z6ST3ZKZBXAVCNFSM6AAAAACIDRVS3OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTINBVGIZDKNJXHA> . You are receiving this because you were mentioned.Message ID: <GSA/data. ***@***.***>

-- *Tim Lowden* Product Manager Data.gov Technology Transformation Services U.S. General Services Administration

[jbrown-xentity]

To summarize this: these are the "issues" or "outstanding concerns" that need to be addressed before moving forward.

The next ticket will provide the necessary research for making the decisions and plan to manage the schema and set data.gov up for success, and set up data providers for success.

Team meeting and review is complete, moving this to done.