Skip to main content

Version 0.4.0: a new route for Entity metadata, and rules for date filters

· 3 min read
John Ferlito
Engineer @ Inodes

Version 0.4.0 of the RO-Crate API specification has two breaking changes. The route for an Entity's RO-Crate Metadata Document has a new name. Date search filters now have exact rules.

A new route for Entity metadata​

GET /entity/{id}/rocrate is now GET /entity/{id}/metadata. HEAD changes in the same way.

The old name was wrong. The endpoint returns an RO-Crate Metadata Document, not an RO-Crate. The new name also matches GET /ro-crate/{id}/metadata, which returns the RO-Crate Metadata Document of a deposited RO-Crate.

The old route is removed. It has no alias, and servers return 404 for it.

Generated client libraries get new method names: getEntityCrate is now getEntityMetadata, and headEntityCrate is now headEntityMetadata.

Rules for date filters​

Before 0.4.0, the specification said only that date filter values are "ISO 8601 strings". It did not say what a date without a time means. So servers did different things with this filter:

{
"filters": {
"createdAt": { "gte": "2020-01-01", "lte": "2020-12-31" }
}
}

Some servers included all of 31 December. Other servers stopped at the start of 31 December, and dropped the results from that day.

These are the rules now:

  • A value is a date (YYYY-MM-DD) or a full RFC 3339 date-time.
  • A date means the full day in UTC. The filter above includes all of 2020.
  • A date-time without a time zone is UTC.
  • The same rules apply to exact values. "2020-12-31" matches all of that day. "2020-12-31T10:00:00Z" matches only that instant.
  • The server rejects other values, such as 2020 or 2020-12, with a 400 ValidationError.

A range bound must also have the same JSON type as its filter: a string for a date filter, a number for a number filter.

The Capabilities guide has more examples.

Other changes​

What to do​

Servers:

  • Serve /entity/{id}/metadata, and remove /entity/{id}/rocrate.
  • Treat a date as the full UTC day. Reject other date forms with a 400.
  • Set apiVersion to 0.4.0 in /capabilities.

Clients:

  • Call /entity/{id}/metadata.
  • Regenerate client libraries, and use the new method names.

The changelog lists all the changes in 0.4.0.