Code.gov Schema Feedback

[froi]

At Code.gov we are constantly looking at how to improve our processes and those of our partners. A central part of these improvements in our JSON schema.

In the past, we have updated the schema from an initial 1.0.0 release to a 2.0.0 with little feedback. We would like to remedy that by asking for feedback on our future releases starting with version 2.0.1.

In this new release, we have added additional optional fields that we feel could benefit our users. We would like feedback on these fields and any other additional you feel should be considered.

The new schema can be viewed here.

We look forward to your ideas!

[Scotchester]

@froi Would it be possible to get an isolated list of what the new optional fields are so we don't have to parse a big JSON file to figure that out?

Also, are previously implemented fields up for discussion? If so, I'd like to reopen the discussion about whether laborHours should be optional.

[froi]

Hey @Scotchester, thanks for the feedback.

Let's start with the optional fields, they are:

• target_operating_systems: An array string field where you can indicate what operating systems the software is compatible with. Acceptable values are defined by an enum and are the following:

  • unix
  • linux
  • windows
  • macOS
  • other

• additional_information: This field is a dynamic field placed for any information that is unique to an agency, but still public. This field is not meant to be used as an "internal information" field, but for information that would be useful to users to better understand what the repository is about. Think metadata for the metadata (so much meta).

are previously implemented fields up for discussion?

The complete schema is up to discussion. We want this to be as collaborative as possible and they are meant to change as needs arise. At the end of the day, all feedback will be taken into consideration and discussed by the team and if it is of benefit to the program, project, product or our users and partners we will see how we can make it work.

Specifically for the laborHours field you can ping @RicardoAReyes. He's been working with agencies to figure this out.

Hope that helps 😄

[jbjonesjr]

@froi for targeted system, perhaps a N/A option? If someone is building a purely web-based, O/S agnostic app, I think it makes more sense to target no OS than to target them all. thoughts?

[DanielJDufour]

@jbjonesjr , good point. It's an interesting case that I hadn't considered yet. I'm thinking of user stories that might shed some insight into what path we should take. If a user is looking for a code analysis tool that works on MacOS or iOS, they would want to activate a filter for operating system by selecting MacOS or iOS. However, if we have N/A, they wouldn't see all of the code analysis tools that are browser-based. Thus, I'd prefer to keep target_operating_system as it is, but I'm open to persuasion given other user stories :-)

We might also want to consider changing the name to supported_operating_systems if target_operating_system we hear that this is causing confusion among our users.

[jbjonesjr]

@DanielJDufour makes sense. in that case, i would want things that work on my MAC, which could be desktop/native apps, or web apps. I'm thinking about it more from the data entry perspective and ensuring people enter the right information. It might be worth separating the concerns of tool discovery from tool cataloging, allowing a metadata value like web-technology that would then be translated to all OS by the front end?

Definitely an interesting question.

[froi]

Sorry I've been MIA. @jbjonesjr @DanielJDufour very good ideas.

I think changing the field name to supported_operating_system make a ton of sense.

The distinction of tool discovery vs tool cataloging hadn't crossed my mind and would be an interesting topic to explore.

[jcastle-zz]

We have an internal meeting with agencies to discuss schema 2.0.1. This thread will be considered.