API Metadata

[Pulsifer, Michael - OPA]

As we nearing release of v2 of our API this June (for real, this time), we have been having conversations about metadata.  One of the people I was talking to in one of our agencies basically expressed no interest in cooperating unless the API metadata conformed to Dublin Core.  Searching for any direction from OMB has come up empty for me thus far.  At the same time, I’ve been observing a lot of interest in Swagger.  Are these compatible or mutually exclusive?  Is there direction from OMB?

Mike Pulsifer

Technical Manager

Division of Enterprise Communications

Office of Public Affairs

U.S. Department of Labor

desk: (202) 693-4946

mobile: (202) 256-1474

[Philip Ashlock - XAAB]

Mike, 

I think you and the person interested in Dublin Core are talking about metadata at different levels of abstraction. An API can use Dublin Core Terms for fields in the data (like column headings in a spreadsheet) and then Swagger can be used to describe those fields (the name of the field, the datatype, etc) . The Project Open Data metadata schema uses Dublin Core terms for a lot of different fields and uses JSON Schema to describe those. JSON Schema is actually part of Swagger, it's what it uses to describe models for the data sent and received in API calls, so in a sense the Project Open Data schema is an example of how these are compatible. 

i.e. you'd use Dublin Core terms for the data and parameters in the API, and then you'd use Swagger to describe the data and parameters. 

Happy to elaborate more and give examples if that helps. 

Phil

--
You received this message because you are subscribed to the Google Groups "US Government APIs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to us-government-a...@googlegroups.com.
To post to this group, send email to us-govern...@googlegroups.com.
Visit this group at http://groups.google.com/group/us-government-apis.

--

Philip Ashlock
Chief Architect, Data.gov
U.S. General Services Administration

[mje...@gmail.com]

Phil/Mike -

Good distinction between Dublin Core and Swagger... This might be an opportunity to open up the conversation a little wider...

Metadata is critical to understanding the data that is made available in an API. One of Mike Bracken's points (UK CDO) has always been that govies (and all open data providers) should make their machine-readable data - machine-understandable as well. Web-APIs are a great way to get the data but when it comes to understanding the data, there appears to be several options.

I've seen some cases where agencies provide a data dictionary (html), some that don't provide a data dictionary, some that provide a versioned, static document (pdf), some that provide a schema (json schema or xml schema). The last one is interesting to me because it is possible for developers to better understand the content (straight from the source).

Any thoughts on the above?

Many thanks
-Marcel

[William A Rankin (CENSUS/ADRM FED)]

Here at the Census Bureau, we make the data dictionary available in HTML, XML, and JSON for all of our API datasets. As we extend our output content types, the amount of metadata we expose expands, and the HTML becomes more difficult to view (think more and more columns), while the other two output types extend very well. We have a few internal applications using our dictionary schema to help their processing. One of the challenges we've discovered is that it requires standardization of the metadata model used to generate the data dictionaries, which can be tricky when multiple applications (API file generation being only one of them) use the same metadata scheme.

Also, I should give credit to our data content providers/subject matter experts who also create data dictionary content for viewing as static documents (PDF), which are usually found in the same area for bulk downloads using FTP.

Thanks,
Bill Rankin
DataWeb Team
U S Census Bureau

________________________________________
From: us-govern...@googlegroups.com <us-govern...@googlegroups.com> on behalf of mje...@gmail.com <mje...@gmail.com>
Sent: Saturday, March 28, 2015 12:45 PM
To: us-govern...@googlegroups.com
Cc: Pulsifer...@dol.gov
Subject: Re: [Gov't APIs] API Metadata