Migrating from DCAT-US v1.1 to v3.0

See an error on this page or have other feedback? Email us at DataGovHelp@gsa.gov

Overview

This guide covers the minimum changes needed to make your existing v1.1 data.json file valid against the v3.0 schema. Work through the steps in order — steps 1 through 4 address breaking changes that will cause validation failures. Steps 5 through 8 are structural changes required for correct v3.0 implementation. After completing all steps, run your updated data.json against the v3.0 validation script: jsonschema/test_json_schema.py Note: the generated reference documentation in jsonschema/docs/ currently shows all fields as Optional regardless of their actual requirement level. This is a known issue. Trust the requirement levels in the JSON schema files and on the reference pages, not the generated docs. —

Breaking changes — fix these first

These are changes where your existing v1.1 values will fail v3.0 schema validation.

Step 1 — Fix modified

If you use repeating intervals like R/P1D or R/P1Y in modified, replace them with the actual date the data last changed. Move your update frequency to accrualPeriodicity using a plain-language code.

Add accrualPeriodicity to express update frequency:

"accrualPeriodicity": "annually" 

Accepted values include: daily, weekly, monthly, quarterly, annually, irregular. ISO 8601 repeating duration format (e.g., R/P1Y) is also still accepted. —

Step 2 — Fix temporal

Replace the v1.1 ISO 8601 interval string with an array of PeriodOfTime objects. At least one of startDate or endDate is required per object. Open-ended periods are valid — omit endDate for ongoing datasets.

"temporal": [
  {
    "@type": "PeriodOfTime",
    "startDate": "2000-01-15",
    "endDate": "2010-01-15"
  }
]

"temporal": [
  {
    "@type": "PeriodOfTime",
    "startDate": "2020-01-01"
  }
]

Step 3 — Fix spatial

Replace the v1.1 plain string or ad-hoc GeoJSON with an array of Location objects. No fields are required on Location — include prefLabel at minimum, and add bbox for geospatial precision.

"spatial": [
  {
    "@type": "Location",
    "prefLabel": "United States"
  }
]

"spatial": [
  {
    "@type": "Location",
    "prefLabel": "Continental United States",
    "bbox": "POLYGON((-125 24, -66 24, -66 50, -125 50, -125 24))"
  }
]

Step 4 — Fix language

Replace RFC 5646 language tags with two-letter ISO 639-1 codes. The v3.0 schema enforces a maximum length of two characters — values like en-US will fail validation.

This applies to language on Dataset, Distribution, DataService, and Catalog. —

Structural changes — required for correct v3.0 implementation

These changes will not cause immediate validation failures but are required to correctly implement v3.0.

Step 5 — Update conformsTo on the Catalog

Change the plain string URI to a Standard object pointing to DCAT-US v3.0.

"conformsTo": {
  "@type": "Standard",
  "title": "DCAT-US 3.0",
  "identifier": "https://resources.data.gov/dcat-us/3.0.0"
}

Step 6 — Remove @context and describedBy from the Catalog

Both fields have been removed at the catalog level in v3.0. Delete these lines from your catalog object.

// Remove these lines from your catalog: "@context": "https://project-open-data.cio.gov/v1.1/schema/catalog.jsonld", "describedBy": "https://project-open-data.cio.gov/v1.1/schema/catalog.json" 

Step 7 — Replace accessLevel with accessRights

accessLevel is not in the v3.0 schema. Add accessRights as a free-text string alongside your existing accessLevel field. Until updated OMB guidance is issued, keep accessLevel in your records — the v3.0 schema will not reject it, and existing OMB policy still requires it.

Step 8 — Add license to Distribution objects

In v3.0, license is defined at the Distribution level per W3C DCAT. The recommended approach is to add license to each Distribution object. You do not need to remove it from the Dataset level during the transition period — the v3.0 schema will not reject records that include it there.

{
  "@type": "Dataset",
  "license": "https://creativecommons.org/publicdomain/zero/1.0/",
  "distribution": [...]
}

{
  "@type": "Dataset",
  "distribution": [
    {
      "title": "Dataset CSV",
      "downloadURL": "https://agency.gov/data/dataset.csv",
      "mediaType": "text/csv",
      "license": "https://creativecommons.org/publicdomain/zero/1.0/"
    }
  ]
}

If all your distributions share the same license you will need to add it to each one individually. —

You are done with the minimum migration

After completing steps 1 through 8 your records should validate against the v3.0 schema. Run your updated data.json against the validation script at jsonschema/test_json_schema.py to confirm. —

Additional improvements

These changes are not required for validation but improve the quality and interoperability of your metadata. Work through them when you are ready.