search

18F / data-inventory

18F's contributions to the GSA enterprise data inventory and public data listing
4 stars 3 forks source link

Should we be leveraging the about.yml format instead? #22

Open harrisj opened 9 years ago

harrisj commented 9 years ago

I'm wondering if we should figure out a better way to use the about.yml format to get the information we need to generate and keep this data up to date. There are several options we could explore

Populate/track some of our data.json data from the existing about.yml fields:

  1. The POC email is in the current about.yml, combined with lookup against team API, this would answer a lot of our needs for finding/tracking POC on content
  2. The links section maps to references. We could also look for specifically tagged links for API documentation.

We could also consider tweaking the about_yml format some more to allow apps to indicate datasets/API distributions within the about.yml file itself. This would allow us to distribute the work of entering/keeping this data up to date across all the projects:

  1. Perhaps add a datasets and apis tree of the YML with subfields that apply (although in some cases we could also infer them)
  2. A process for generating the GSA's requested CSV (or some other format suitable for them) from the about.yml files
  3. An internal site for tracking which APIs/datasets have been posted to the GSA already (turning this workflow into an app instead)
  4. A way of noticing changes between scans and flagging us so we can notify GSA about them

It's a bit more work in the short run, but it has an advantage of decentralizing our own work collecting/maintaining these records so in the long run it might be easier.

What do you think @gbinal and @mbland?

mbland commented 9 years ago

The more we can use .about.yml the better, methinks. All of this sounds possible.

gbinal commented 9 years ago

The flipside though is that it adds complexity to the about.yml schema and program, essentially increasing the burden for everyone's adoption. I'm not sure if that's a price worth paying for the benefit we'd gain.

ultrasaurus commented 9 years ago

I would love to be able to reference API and API documentation in about.yml and have it show up on my product's dashboard page.

cc @gboone

mbland commented 9 years ago

@gbinal We can make the fields optional, so it shouldn't impede anyone. I doubt it'd significantly impact the complexity of the program or the schema, once we hash out what it should look like. Shall we convene a brainstorming session?