Skip to content

Semi Annual Release Cycles

Jump to bottom
Susan Valente edited this page Aug 28, 2026 · 2 revisions

Semi-Annual Release Cycles

Draft for discussion and revision by the DCAT Interagency Maintenance Team and the Data.gov team.

This page describes the proposed semi-annual release cycle for maintaining the DCAT-US v3.0 metadata standard.

DCAT-US v3.0 follows a semi-annual maintenance cycle covering:

  • Schema review
  • Documentation updates
  • Release preparation
  • Agency outreach
  • Deprecation notices
  • Grace periods
  • Annual retrospective review

The DCAT Interagency Maintenance Team governs schema maintenance decisions. The Data.gov team at GSA maintains the DCAT-US repository and coordinates the release cycle.

Major version changes, such as DCAT-US v4.0, are planned separately.

Release Cycle Summary

DCAT-US v3.0 has two planned maintenance release cycles each year.

Cycle Timing Focus
Cycle 1: Spring Release March/April Schema review, non-breaking changes, critical documentation updates, release notes, deprecation notices
Cycle 2: Summer Release and Retrospective July Schema review, summer release, M-25-05 annual compliance reference alignment, documentation updates, agency outreach, annual retrospective

In addition to these release cycles, issues are triaged continuously throughout the year.

Continuous Issue Triage

Issues are triaged on a rolling basis as they are submitted, rather than batched to a specific time of year.

The Data.gov team applies a classification label to each new issue within two weeks of submission.

Issue labels include:

Label Meaning
bug The schema behaves incorrectly or inconsistently with the specification
enhancement A proposed addition or improvement to the schema
question A request for clarification on schema intent or behavior

Issues approved for review in an upcoming release are assigned to the corresponding milestone.

Issues received through Zendesk, CDO Council channels, office hours, or other agency communication channels that are not yet on GitHub may be cross-filed by the Data.gov team.

DCAT-US GitHub Issues:
https://github.com/GSA/dcat-us/issues

Cycle 1: Spring Release

Timing

Cycle 1 occurs in March/April.

Purpose

The spring release provides a structured opportunity to review and release approved non-breaking schema changes, resolve critical documentation issues, validate examples, and issue deprecation notices for potential future breaking changes.

Cycle 1 may include:

  • Approved non-breaking schema changes
  • Schema bug fixes
  • Clarifications to field descriptions or usage guidance
  • Critical documentation updates
  • Example validation
  • Changelog updates
  • Release notes
  • Deprecation notices for breaking changes planned for a later cycle

Cycle 1 Schema Review

During Cycle 1, the DCAT Interagency Maintenance Team reviews issues in the Cycle 1 milestone and assigns a disposition.

Possible dispositions include:

Disposition Meaning
Approved for PR The issue should move forward as a pull request
Deferred The issue should be reconsidered in a future cycle
Closed as won’t fix The issue will not be addressed through a schema or documentation change
Needs more information Additional information is needed before a decision can be made
Documentation update only The issue should be addressed through documentation, examples, FAQs, or guidance rather than a schema change

Cycle 1 Pull Requests

For issues approved as non-breaking changes, pull requests are opened.

Approved pull requests may include:

  • Schema corrections
  • New optional fields
  • Updated descriptions
  • Clarified usage notes
  • Documentation-aligned schema fixes
  • Non-breaking validation improvements

Breaking changes approved in Cycle 1 are deferred to Cycle 2 at the earliest.

If a breaking change is planned for a future cycle, a deprecation notice must be issued as part of Cycle 1 outreach.

A minimum 90-day agency implementation window is required before enforcement of breaking changes.

Cycle 1 Security Considerations

Schema changes touching any of the following fields must include a security considerations note in the pull request:

  • accessRestriction
  • useRestriction
  • cuiRestriction

The security considerations note should describe:

  • Which field is affected
  • What behavior is changing
  • Whether the change affects validation
  • Whether the change affects agency implementation
  • Whether the change affects representation of access, use, or CUI-related restrictions
  • Any recommended agency review or implementation considerations

Cycle 1 Documentation

During Cycle 1, documentation work focuses on resolving critical issues and confirming that documentation aligns with the live schema.

Cycle 1 documentation tasks include:

  • Resolve all P1, or critical, documentation issues on resources.data.gov
  • Validate all example records in documentation against the current schema
  • Audit all DCAT-US pages on resources.data.gov against the live schema
  • File issues for any pages that are out of sync
  • Identify FAQs or guidance updates based on recurring implementation questions

Cycle 1 Release Activities

Cycle 1 release activities include:

  • Merge approved pull requests into the main branch
  • Tag a point release using semantic versioning, such as v3.1
  • Include a changelog entry describing all changes in the release tag
  • Confirm whether the conformsTo URI requires updating for the new version
  • Confirm release notes are ready
  • Confirm documentation updates are complete or tracked
  • Confirm outreach language is ready

Cycle 1 Agency Outreach

Release notes should be published within two weeks of the release tag.

Release notes should be shared through:

  • CDO Council channel
  • Data.gov mailing list
  • GitHub release notes

Cycle 1 outreach should include:

  • Release version
  • Release date
  • Summary of changes
  • Link to the changelog
  • Description of schema changes
  • Description of documentation changes
  • Any new requirements
  • 90-day grace period before any new requirements are enforced
  • Deprecation notices for changes planned for Cycle 2, if applicable
  • Links to updated documentation
  • Contact information for questions

Cycle 1 Outputs

Expected Cycle 1 outputs include:

  • Reviewed Cycle 1 milestone issues
  • Issue dispositions
  • Approved and merged pull requests
  • Point release tag
  • Changelog entry
  • Release notes
  • Documentation updates
  • Validated examples
  • Deprecation notices, if applicable
  • Agency outreach message
  • Follow-up issues or tasks, if needed

Cycle 2: Summer Release and Retrospective

Timing

Cycle 2 occurs in July.

The July release aligns with the M-25-05 annual compliance reference date.

Cycle 2 also includes the annual retrospective.

Purpose

The summer release provides a structured opportunity to review and release approved changes, include eligible breaking changes that received prior notice, update documentation and migration guidance, communicate changes to agencies, and review annual implementation trends.

Cycle 2 may include:

  • Approved non-breaking schema changes
  • Eligible breaking changes that received prior deprecation notice
  • Schema bug fixes
  • Clarifications to field descriptions or usage guidance
  • P1 and P2 documentation updates
  • Migration guidance updates
  • Changelog updates
  • Release notes
  • Agency outreach
  • Annual retrospective findings

Cycle 2 Schema Review

During Cycle 2, the DCAT Interagency Maintenance Team reviews issues in the Cycle 2 milestone and assigns a disposition.

Possible dispositions include:

Disposition Meaning
Approved for PR The issue should move forward as a pull request
Deferred The issue should be reconsidered in a future cycle
Closed as won’t fix The issue will not be addressed through a schema or documentation change
Needs more information Additional information is needed before a decision can be made
Documentation update only The issue should be addressed through documentation, examples, FAQs, or guidance rather than a schema change

Cycle 2 Pull Requests

For issues approved as non-breaking changes, pull requests are opened.

Breaking changes approved in Cycle 1 with a prior deprecation notice may be included in Cycle 2, provided the minimum 90-day agency implementation window has been met.

Approved pull requests may include:

  • Schema corrections
  • New optional fields
  • Updated descriptions
  • Clarified usage notes
  • Eligible breaking changes with prior notice
  • Documentation-aligned schema fixes
  • Validation improvements

Cycle 2 Security Considerations

Schema changes touching any of the following fields must include a security considerations note in the pull request:

  • accessRestriction
  • useRestriction
  • cuiRestriction

The security considerations note should describe:

  • Which field is affected
  • What behavior is changing
  • Whether the change affects validation
  • Whether the change affects agency implementation
  • Whether the change affects representation of access, use, or CUI-related restrictions
  • Any recommended agency review or implementation considerations

Cycle 2 Documentation

During Cycle 2, documentation work focuses on resolving P1 and P2 documentation issues, updating migration guidance, and ensuring the changelog and examples remain current.

Cycle 2 documentation tasks include:

  • Resolve all P1 and P2 documentation issues on resources.data.gov
  • Publish updated migration guidance within 30 days of release if any field-level changes affect existing data.json implementations
  • Update the changelog on resources.data.gov
  • Confirm examples and implementation guidance remain aligned with the live schema
  • Identify FAQs or guidance updates based on recurring implementation questions
  • File follow-up issues for documentation that cannot be completed before release

Cycle 2 Release Activities

Cycle 2 release activities include:

  • Merge approved pull requests into the main branch
  • Tag a point release using semantic versioning, such as v3.2
  • Include a changelog entry describing all changes in the release tag
  • Confirm whether the conformsTo URI requires updating for the new version
  • Confirm release notes are ready
  • Confirm documentation updates are complete or tracked
  • Confirm migration guidance is complete or scheduled, if needed
  • Confirm outreach language is ready

Cycle 2 Agency Outreach

Release notes should be published within two weeks of the release tag.

Release notes should be shared through:

  • CDO Council channel
  • Data.gov mailing list
  • GitHub release notes

Cycle 2 outreach should include:

  • Release version
  • Release date
  • Summary of changes
  • Link to the changelog
  • Description of schema changes
  • Description of documentation changes
  • Any new requirements
  • Any breaking changes that were previously noticed
  • 90-day grace period before any new requirements are enforced
  • Links to updated documentation or migration guidance
  • Contact information for questions

Cycle 2 outreach may also include hosting or contributing to a CDO Council touchpoint to collect agency implementation questions and blockers for schema team awareness.

Cycle 2 Outputs

Expected Cycle 2 outputs include:

  • Reviewed Cycle 2 milestone issues
  • Issue dispositions
  • Approved and merged pull requests
  • Point release tag
  • Changelog entry
  • Release notes
  • Documentation updates
  • Migration guidance, if needed
  • Eligible breaking changes, if prior notice and implementation window requirements are met
  • Agency outreach message
  • Annual retrospective notes
  • Annual compliance support summary
  • Next-cycle priorities

Annual Retrospective

The annual retrospective occurs in July as part of Cycle 2.

Purpose

The annual retrospective reviews implementation experience from the prior year and identifies priorities for the next annual maintenance cycle.

The retrospective supports:

  • Better implementation guidance
  • Improved documentation
  • Better validation and harvesting outcomes
  • Identification of recurring agency blockers
  • Prioritization of future schema clarifications or changes
  • Targeted agency implementation support

Retrospective Activities

Annual retrospective activities include:

  • Review harvest validation error trends for the year using New Relic data
  • Identify systemic field-level error patterns that may warrant schema clarification or guidance updates
  • File issues as needed for schema clarification, documentation updates, or implementation guidance updates
  • Publish an annual compliance summary identifying agency cohorts that may benefit from targeted implementation assistance
  • Share the compliance summary with the DCAT Interagency Maintenance Team
  • Document lessons learned
  • Identify priorities for the next annual cycle

Compliance Summary

The annual compliance summary is an implementation support tool.

It is intended to help identify:

  • Common implementation challenges
  • Agencies or agency cohorts that may benefit from targeted assistance
  • Field-level error patterns
  • Documentation gaps
  • Areas where additional examples, FAQs, or guidance may be needed

The compliance summary is not an enforcement document.

Change Types and Release Rules

The maintenance process uses different release rules depending on the type of change.

Change Type Example Earliest Release Notice Required
Non-breaking addition New optional field Next cycle None
Non-breaking clarification Updated field description Next cycle None
Breaking change Removed field, changed enum Cycle after notice Deprecation notice in prior cycle outreach

Non-Breaking Additions

A non-breaking addition is a change that adds functionality or expressiveness without requiring agencies to modify existing valid metadata records.

Examples include:

  • Adding a new optional field
  • Adding an optional object
  • Adding optional guidance
  • Adding an example that does not change validation expectations

Earliest release:

  • Next maintenance cycle, if approved

Notice required:

  • None, unless the team determines agency outreach would be helpful

Non-Breaking Clarifications

A non-breaking clarification improves understanding without changing validation expectations or requiring agencies to change existing valid metadata.

Examples include:

  • Updating a field description
  • Clarifying a usage note
  • Correcting documentation
  • Adding implementation examples
  • Clarifying expected formats without changing schema behavior

Earliest release:

  • Next maintenance cycle, if approved

Notice required:

  • None, unless the clarification is likely to affect agency interpretation or implementation behavior

Breaking Changes

A breaking change is a change that may cause existing valid metadata to become invalid or require agencies to modify existing implementations.

Examples include:

  • Removing a field
  • Changing an enum
  • Changing a field from optional to required
  • Changing allowed values
  • Changing validation behavior in a way that causes previously valid records to fail
  • Changing structure in a way that affects existing data.json implementations

Earliest release:

  • Cycle after notice

Notice required:

  • Deprecation notice in prior cycle outreach

Breaking changes require a minimum 90-day agency implementation window before enforcement.

Deprecation Notices

A deprecation notice should be issued when a breaking change is planned for a future release.

Deprecation notices should include:

  • Affected field, enum, or schema area
  • Description of the planned change
  • Reason for the change
  • Expected release timing
  • Agency implementation impact
  • Minimum 90-day implementation window
  • Recommended agency action
  • Where agencies can ask questions or provide feedback

Deprecation notices should be included in release outreach and GitHub release notes.

Grace Period

Each release should include a 90-day grace period before any new requirements are enforced.

The grace period gives agencies time to:

  • Review release notes
  • Review updated documentation
  • Assess implementation impact
  • Update metadata generation processes
  • Update data.json files
  • Validate updated harvest sources
  • Ask implementation questions
  • Coordinate internally

Semantic Versioning

Point releases should use semantic versioning.

Examples:

  • v3.1
  • v3.2

The release tag should include a changelog entry describing all changes in the release.

Major version changes, such as v4.0, are planned separately and are not part of the DCAT-US v3.0 semi-annual maintenance cycle.

conformsTo URI Review

For each release, the Data.gov team should confirm with the schema team whether the conformsTo URI requires updating for the new version.

This review should occur before release tagging.

Considerations may include:

  • Whether the release changes schema behavior
  • Whether the release changes validation expectations
  • Whether the release includes breaking changes
  • Whether the release should be distinguishable in agency metadata
  • Whether documentation or implementation guidance needs to reference the updated URI

Suggested Annual Timeline

The following timeline may be used to operationalize the release cycles.

Month Activity
Ongoing Continuous issue triage within two weeks of issue submission
January Cycle 1 pre-planning and milestone review
February Cycle 1 DCAT Interagency Maintenance Team schema review
February/March Agency feedback meeting, if needed
March Cycle 1 release readiness meeting
March/April Spring release, release notes, and outreach
April/May Monitor agency questions and implementation feedback
May Cycle 2 pre-planning and milestone review
June Cycle 2 DCAT Interagency Maintenance Team schema review
June Agency feedback meeting, if needed
Late June/July Cycle 2 release readiness meeting
July Summer release aligned with M-25-05 annual compliance reference date
July Annual retrospective
August Share compliance support summary and next-cycle priorities, if applicable
September–December Continue triage, documentation updates, and implementation support

Release Readiness Checklist

Before tagging a release, the Data.gov team and DCAT Interagency Maintenance Team representative should confirm the following.

  • Issues assigned to the cycle milestone have been reviewed.
  • Issue dispositions have been documented.
  • Approved pull requests are ready to merge.
  • Breaking changes have received prior deprecation notice, if applicable.
  • Minimum 90-day agency implementation window has been considered, if applicable.
  • Security considerations notes are included for changes touching:
    • accessRestriction
    • useRestriction
    • cuiRestriction
  • Documentation updates are complete or tracked.
  • Example records have been validated against the current schema.
  • Changelog entry is drafted.
  • GitHub release notes are drafted.
  • conformsTo URI update decision has been confirmed.
  • Agency outreach message is drafted.
  • Grace period language is included, if applicable.
  • Deprecation notice language is included, if applicable.

Release Notes Checklist

  • Release version
  • Release date
  • Summary of changes
  • Schema changes
  • Documentation changes
  • Bug fixes
  • Enhancements
  • Clarifications
  • Breaking changes, if applicable
  • Deprecation notices, if applicable
  • Grace period information
  • Migration guidance, if applicable
  • Link to changelog
  • Link to updated documentation
  • Contact information for questions

DCAT-US 3 Implementation Support

Meetings

Implementation Resources

Data.gov Team Process

FAQs

Reference

DCAT Interagency Maintenance Team

Clone this wiki locally