
UK Government Selects OpenAPI v3 - edent
https://technology.blog.gov.uk/2019/10/02/improve-csvs-and-api-descriptions-with-these-open-standards-board-recommendations/
======
jsingleton
This also covers CSV as well as APIs.

Links:

[https://openapi.tools/](https://openapi.tools/)

[https://tools.ietf.org/html/rfc4180](https://tools.ietf.org/html/rfc4180)

While using the open API spec is good, I'd say the standardisation of CSV data
will have more impact. More of the open data available is in the form of
historic reports rather than real-time:
[https://data.gov.uk/](https://data.gov.uk/) (e.g.
[https://data.gov.uk/dataset/27dd8d7f-c58b-4de3-bf0d-81058465...](https://data.gov.uk/dataset/27dd8d7f-c58b-4de3-bf0d-810584651f05/uk-
s-carbon-footprint-1990-to-2009))

~~~
ThePhysicist
I can't find any mention of CSV in the OpenAPI documentation or the first link
you provided, can you elaborate a bit how this works?

~~~
atroche
I think he means that the UK govt has mandated a particular CSV standard for
tabular data, at the same time. I think you're right that OpenAPI has nothing
to do with CSV.

~~~
bloak
Yes. CSV with the obvious extra conditions "UTF-8" and "one header row" is
fairly interoperable, but note: "when you’re using Excel for Windows to load a
file that is UTF-8 without a BOM, you can resolve the display of non-ASCII
characters by using the ‘import text’ option". If a Windows user just clicks
on the file then sometimes UTF-8 is interpreted as some 8-bit encoding and you
get mojibake. Nevertheless, you shouldn't add a BOM because the standard
doesn't permit that and it might cause all sorts of problems on other systems.

~~~
java-man
Mojibake

[https://en.wikipedia.org/wiki/Mojibake](https://en.wikipedia.org/wiki/Mojibake)

love this word!

------
petepete
This is great news.

As someone working on GOV.UK projects and regularly working with large,
unwieldy CSVs I can't recommend CSVKit[0] highly enough. Being able to go from
CSV to PostgreSQL in one or two simple steps is _priceless_ for me.

[0]
[https://csvkit.readthedocs.io/en/latest/](https://csvkit.readthedocs.io/en/latest/)

~~~
jimsmart
I've had good success using Postgres' built-in CSV import/export command
(COPY) in the past — depends on one's workflow, obviously!

[https://www.postgresql.org/docs/12/sql-
copy.html](https://www.postgresql.org/docs/12/sql-copy.html)

------
dazhbog
Anyone know/recommend any API schemas/standards for REST APIs that allow
machines to discover their resources?

For example I see OpenApi v3 mentioned here (which uses a yaml file to give
context) and I am also familiar with NGSIv2[1] which will get standardized by
ETSI supposedly (NGSI-LD[2]). NGSI seems to embed info in the json so that
your application can know if this float is Celsius or Fahrenheit.

Any other open options?

[1]:
[https://fiware.github.io/specifications/ngsiv2/stable/](https://fiware.github.io/specifications/ngsiv2/stable/)
[2]: [https://fiware-datamodels.readthedocs.io/en/latest/ngsi-
ld_f...](https://fiware-datamodels.readthedocs.io/en/latest/ngsi-
ld_faq/index.html)

~~~
madcapmac
Take a look at JSON-LD and Hydra

[https://json-ld.org/](https://json-ld.org/)

[https://www.hydra-cg.com/](https://www.hydra-cg.com/)

------
rocketpastsix
Coauthor of openapi.tools here. If y'all have suggestions about things we can
do to make the project better, we are all ears!

~~~
RangerScience
This is really cool! The one feature I would have asked for is already in
place: authorization - so that's super cool.

That said, hmm, what do you feel like OpenAPI learned (so as not to repeat)
from the pitfalls of SOAP WSDLs?

~~~
rocketpastsix
That is a fascinating question. Mostly because I wasn't around for SOAP. I
started my development career kind of with the rise of REST. I've only ever
used REST personally, so I couldn't really tell you. Looking up WSDL, I can
tell you one thing I've noticed with OpenAPI is that it is both incredibly
descriptive, and yet not in the way. I can look at an OpenAPI file, figure out
what is going really quickly and get working. With WSDL/XML you have to parse
the whole XML schema to really understand what is going on.

------
yxhuvud
I wish tooling was available for the company I work for to use v3. So much of
the ecosystem is stuck on v2 or worse.

~~~
atroche
What's the thing you miss most from v3 working in v2?

~~~
jimlikeslimes
The oneOf keyword is really handy. I actually resorted to implementing the
"sub-schema" validation using another tool when this wasn't available.

I think it's in JsonSchema validation and Open Api v3 but not v2.

------
mintyc
One of the criticisms of OpenAPI is the verbosity of the schema definition.

I've seen a couple of meta generator projects that generate OpenAPI specs from
a meta description.

Is anything being done 'officially' to provide an abbreviated form for simpler
use cases?

~~~
codegladiator
Why does it matter ? It's not supposed to be read by humans.

~~~
tofflos
It is supposed to be read by humans: "The format is easy to learn and readable
to both humans and machines."

Source
[https://swagger.io/docs/specification/about](https://swagger.io/docs/specification/about)

------
amanzi
The CSV standard looks very sensible and reasonable.

