Update on 3.0 Schema changes

Technical
1

Hi all,

Here is a summary of what was agreed at the last workgroup meeting of 2022 with regards to 3.0 schema changes along with the proposed next steps.

What we’ve agreed on so far:

3.0 remaining questions were discussed and all agreed to substantiating the provisional changes made by David.

Next Steps:

ODS will update the documentation accordingly and let everyone know via the forum when this has been completed.

Please note: When you visit the docs site it will default to the ‘latest’ version of the documentation. To view the updated version you will need switch to ‘3.0-dev-update’. You can do so by following this direct link, or following the instruction below:

1027×757 139 KB

API specifications: endpoint requirements

What we’ve agreed on so far:

The following has been agreed as a minimum:

  1. A /service endpoint that contains a paginated list of limited service fields example 1 AND a /service/{id} endpoint which contains a single full service defined by service 1 json schema (this is what OpenReferral UK currently do)

All are in agreement that further API endpoints ought to be recommended in the standard such as: organization, taxonomy, service_at_location etc, but does not need to happen right now.

Next steps:

ODS will write documentation to reflect the above decision.

Representation format(s): Requirements and recommendations (API vs datapackage)

What has been decided/agreed.

All are in agreement that use of the API should be required in order to be considered HSDS compliant.

We also recognize that there are many instances in which stakeholders might be more capable of producing CSVs bundled by a data package than an API – and we have yet to reach consensus on the preferred way to offer guidance and tooling that might enable such outputs to become ‘compatible’ with the new standard.

From a US perspective, holding off with any decisions around this for now and focusing on getting 3.0 published seems to be favourable.

The issue with this from an ODS perspective when it comes to writing the documentation is that it’s difficult to remain completely neutral, without specifying methods of publication options.

Proposal

Format/Layout

1/ ODS propose the re-formatting the documentation to prioritize the API specs, essentially switching the API and datapackage as explained by David in this post.

Language

2a/ ORUK - Add a separate UK Compliance page to the documentation as per Devin’s suggestion here.

2b/ Elsewhere, in response to concerns expressed by Devin and Skyler this thread we propose the use of the term ‘recommended’ regarding use of a valid API and ‘alternate’ regarding the use a Datapackage.

API specifications: /service and/or /organization as top-level entity

What we’ve agreed on so far:

There is agreement amongst the workgroup that a /services endpoint returning the specified schema will be required at a minimum.

We will provide specifications for /organization and others; these will not be required, but if implemented must be implemented in the manner specified.

There was, however, acknowledgement that is orientated towards application development and that future iterations will specify further endpoints to better support synchronisation and reconciliation.

Next steps:

ODS will write documentation to reflect the above decision.

2 Likes
2

Thanks for this @Dan-ODS.

To date I have always referred to a /services method (and an organizations method etc) as in the ORUK Swagger pages. I think my colleagues had good reason for pluralising the names (@Dominic can you say) and am not sure why we’ve changed to singular here. Is there a good reason?

As a minor point, I’ve previously referred to the “end point” as the API stub and individual “methods” such as /services, /organisations etc. Am I wrong here and is each “method” termed an “endpoint”?

I do want to emphasise that we need a bit more than /services and /services{id} in the UK and we need UK rules around openness. We can document those in UK compliance pages so those no wiggle room for people who are not following the spirit of the standard. Of course I’d recommend the same for outside the UK but that’s for others to decide.

2 Likes
3

No problem, Mike. The reason its plural is because /services returns all services as does organizations. By putting a id on the services path we are restricting the all to a single service, organization etc.

2 Likes
4

Hi @MikeThacker ,

We discussed these points this morning. Our thoughts are:

Pluralising the names
This came about due to the use of singular terms for table names in documentation such as ‘service’ and ‘organization’ but have no issue with adding the s going forward.

Method vs Endpoint
@davidraznick is going to respond to this one.

Additional UK requirements
Yes we are having ongoing discussions about how we will work in UK requirements into the documentation and will link in with you on this in the coming weeks. Happy for you to make a start on drafting something up. No immediate rush though, as it will be more relevant a little down the line as we progress with the upgrade and start to get a feel for the structure.

Dan

2 Likes
5

Happy to have the s in the url paths e.g services. This was done as the ones without the s e.g service where the names of the tables in the datapackage and there in no place we put the correct plurals. I think there is not a “correct” way and people always have a different opinion about it, so going with what you have done already makes sense.

Looking at OpenAPI/Swagger the correct term for somthing like /services is endpoint, or just called the path. See:
https://swagger.io/specification/#paths-object

method should not really be used at it normally means HTTP method (such as GET, POST, PUT).

However, endpoint is confusingly used for both the individual paths and the root path (or the stub as you say) of the entire API.

3 Likes
6

Thanks @davidraznick.

It would be good if we could agree terminology between ourselves to avoid the confusion.

In future I’ll say “stub” for addresses like https://bristol.openplace.directory/o/ServiceDirectoryService/v2/

I guess we’re stuck with “endpoint” for things like
https://northlincs.openplace.directory/o/ServiceDirectoryService/v2/services

2 Likes
7

Hi all,

JTLYK - ‘3.0-dev-update’ has been merged into '3.0-dev’on the docs site. The above link now takes you to 3.0-dev where all updates to the schema will be visible as we work on the upgrade.

Dan