Version 0.4.0: a new route for Entity metadata, and rules for date filters
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
2020or2020-12, with a 400ValidationError.
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
- The specification moved to the CrateWorks organisation. The site is now at https://ro-crate-api.crate-works.org, and the repository is at https://github.com/crate-works/ro-crate-api.
- The PARADISEC server URL is now https://admin-catalog.paradisec.org.au/api/v1/oni.
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
apiVersionto0.4.0in/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.
