From 5748a2155dd63a4771334b2529f9ea93981e9425 Mon Sep 17 00:00:00 2001 From: Ian Lee Date: Thu, 1 Dec 2016 11:36:51 -0800 Subject: [PATCH 1/3] Updated metadata schema based on discussions in #187 --- .../05-metadata-schema-definition.md | 106 ++++++++++-------- 1 file changed, 58 insertions(+), 48 deletions(-) diff --git a/_draft_content/02_compliance/05-metadata-schema-definition.md b/_draft_content/02_compliance/05-metadata-schema-definition.md index ad3cc5be..ab5a99c0 100644 --- a/_draft_content/02_compliance/05-metadata-schema-definition.md +++ b/_draft_content/02_compliance/05-metadata-schema-definition.md @@ -2,65 +2,75 @@ ## Overview -Sections 7.2 and 7.3 of the Federal Source Code Policy require covered agencies to provide an inventory of their 'custom-developed code'. +Sections 7.2 and 7.3 of the Federal Source Code Policy require covered agencies to provide an inventory of their 'custom-developed code'. ## Specification ### File location and contents * `code.json` must live in the root directory of your agency's website. -* `code.json` must include a single object represented as JSON, with key-value pairs according to the list below. +* `code.json` must include a single list represented as JSON, of organization JSON objects, as described below. -### Fields +### Organization JSON Object -#### Required +Each organization JSON object in the `code.json` file, represents the projects for a given agency + organization pairing. The top level fields on the JSON object: * `agency`: [string] The agency acronym. For example "GSA" or "DOD" * `organization`: [string] The organization within the agency that the projects listed belong to. For example, "18F" or "Navy". -* `project`: [object] Contains objects representing each software project - * `name`: [string] The project name - * `description`: [string] A description of the project - * `license`: [`null` or string] The URL of the project license, if available. `null` should be used if not. - * `openSourceProject`: [integer] A value indicating whether or not the project is open source. - * `0`: The project is not open source. - * `1`: The project is open source. - * `governmentWideReuseProject`: [integer] A value indicating whether or not the project is built for government-wide reuse. - * `0`: The project is not built for government-wide reuse. - * `1`: The project is built for government-wide reuse. - * `tags`: [array] A list of string alphanumeric keywords that identify the project. - * `contact`: [object] Information about contacting the project. - * `email`: [string] An email address to contact the project. - -#### Optional - -* `project`: [object] Contains objects representing each software project - * `status`: [string] The development status of the project - * `"Ideation"` - brainstorming phase. - * `"Alpha"` - initial prototyping phase and internal testing. - * `"Beta"` - a project is being tested in public. - * `"Production"` - finished project, with development and maintenance ongoing. - * `"Archival"` - finished project, but no longer actively maintained. - * `vcs`: [string] A lowercase string with the name of the Version Control System in use on the project. - * `repository`: [string] The URL of the public project repository - * `homepage`: [string] The URL of the public project homepage - * `downloadURL`: [string] The URL where a distribution of the project can be found. - * `languages`: [array] A list of strings with the names of the programming languages in use on the project. - * `contact`: [object] Information about contacting the project. - * `name`: [string] The name of a contact or department for the project - * `twitter`: [string] The username of the project's Twitter account - * `phone`: [string] The phone number to contact a project. - * `partners`: [array] A list of strings containing the acronyms of agencies partnering on the project. - * `exemption`: [integer] The exemption that excuses the project from government-wide reuse. - * `1`: The sharing of the source code is restricted by law or regulation, including—but not limited to—patent or intellectual property law, the Export Asset Regulations, the International Traffic in Arms Regulation, and the Federal laws and regulations governing classified information. - * `2`: The sharing of the source code would create an identifiable risk to the detriment of national security, confidentiality of Government information, or individual privacy. - * `3`: The sharing of the source code would create an identifiable risk to the stability, security, or integrity of the agency's systems or personnel. - * `4`: The sharing of the source code would create an identifiable risk to agency mission, programs, or operations. - * `5`: The CIO believes it is in the national interest to exempt sharing the source code. - * `updated`: [object] Dates that the project and metadata have been updated. - * `metadataLastUpdated`: [string] A date in YYYY-MM-DD or ISO 8601 format indicating when the metadata in this file was last updated. - * `lastCommit`: [string] A date in ISO 8601 format indicating when the last commit to the project repository was. - * `sourceCodeLastModified`: [string] A field intended for closed-source software and software outside of a VCS. The date in YYYY-MM-DD or ISO 8601 format that the source code or package was last updated. - +* `projects`: [list] Contains list of `project` objects representing each software project, as defined below. + +### Project JSON Object + +Each project JSON object represents a particular code / software project represented in the code inventory. + +#### Required Project Fields + +Each `project` object requires the following fields: + +* `name`: [string] The project name +* `description`: [string] A description of the project +* `license`: [`null` or string] The URL of the project license, if available. `null` should be used if not. +* `openSourceProject`: [integer] A value indicating whether or not the project is open source. + * `0`: The project is not open source. + * `1`: The project is open source. +* `governmentWideReuseProject`: [integer] A value indicating whether or not the project is built for government-wide reuse. + * `0`: The project is not built for government-wide reuse. + * `1`: The project is built for government-wide reuse. +* `tags`: [array] A list of string alphanumeric keywords that identify the project. +* `contact`: [object] Information about contacting the project. + * `email`: [string] An email address to contact the project. + +#### Optional Project Fields + +The following `project` object fields are optional: + +* `status`: [string] The development status of the project + * `"Ideation"` - brainstorming phase. + * `"Alpha"` - initial prototyping phase and internal testing. + * `"Beta"` - a project is being tested in public. + * `"Production"` - finished project, with development and maintenance ongoing. + * `"Archival"` - finished project, but no longer actively maintained. +* `vcs`: [string] A lowercase string with the name of the Version Control System in use on the project. +* `repository`: [string] The URL of the public project repository +* `homepage`: [string] The URL of the public project homepage +* `downloadURL`: [string] The URL where a distribution of the project can be found. +* `languages`: [array] A list of strings with the names of the programming languages in use on the project. +* `contact`: [object] Information about contacting the project. + * `name`: [string] The name of a contact or department for the project + * `twitter`: [string] The username of the project's Twitter account + * `phone`: [string] The phone number to contact a project. +* `partners`: [array] A list of strings containing the acronyms of agencies partnering on the project. +* `exemption`: [integer] The exemption that excuses the project from government-wide reuse. + * `1`: The sharing of the source code is restricted by law or regulation, including—but not limited to—patent or intellectual property law, the Export Asset Regulations, the International Traffic in Arms Regulation, and the Federal laws and regulations governing classified information. + * `2`: The sharing of the source code would create an identifiable risk to the detriment of national security, confidentiality of Government information, or individual privacy. + * `3`: The sharing of the source code would create an identifiable risk to the stability, security, or integrity of the agency's systems or personnel. + * `4`: The sharing of the source code would create an identifiable risk to agency mission, programs, or operations. + * `5`: The CIO believes it is in the national interest to exempt sharing the source code. +* `updated`: [object] Dates that the project and metadata have been updated. + * `metadataLastUpdated`: [string] A date in YYYY-MM-DD or ISO 8601 format indicating when the metadata in this file was last updated. + * `lastCommit`: [string] A date in ISO 8601 format indicating when the last commit to the project repository was. + * `sourceCodeLastModified`: [string] A field intended for closed-source software and software outside of a VCS. The date in YYYY-MM-DD or ISO 8601 format that the source code or package was last updated. + ## Example `code.json` We've created a [sample `code.json`](https://github.com/presidential-innovation-fellows/code-gov-web/blob/master/_draft_content/02_compliance/schema/code.json). From ae70dd1621085fdc54be19dd2c687b67a45252b2 Mon Sep 17 00:00:00 2001 From: Ian Lee Date: Thu, 1 Dec 2016 11:42:26 -0800 Subject: [PATCH 2/3] Updated sample code.json file to match updates to metadata schema Based on discussion in #187 / #196 --- _draft_content/02_compliance/schema/code.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_draft_content/02_compliance/schema/code.json b/_draft_content/02_compliance/schema/code.json index d23b8c70..5f09ea2f 100644 --- a/_draft_content/02_compliance/schema/code.json +++ b/_draft_content/02_compliance/schema/code.json @@ -1,4 +1,4 @@ -{ +[{ "agency": "DOABC", "organization": "XYZ Department", "projects": [ @@ -33,7 +33,7 @@ { "name": "DOXYZ", "email": "project@doxyz.gov" - } + } ], "exemption": null, "updated": { @@ -43,4 +43,4 @@ } } ] -} +}] From 1d5e8cfdcaddadcb8eede529292d7c51feaeb660 Mon Sep 17 00:00:00 2001 From: Ian Lee Date: Thu, 8 Dec 2016 23:02:08 -0500 Subject: [PATCH 3/3] Updated field types per http://json-schema.org integer -> number list -> array --- .../02_compliance/05-metadata-schema-definition.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_draft_content/02_compliance/05-metadata-schema-definition.md b/_draft_content/02_compliance/05-metadata-schema-definition.md index ab5a99c0..781b610d 100644 --- a/_draft_content/02_compliance/05-metadata-schema-definition.md +++ b/_draft_content/02_compliance/05-metadata-schema-definition.md @@ -17,7 +17,7 @@ Each organization JSON object in the `code.json` file, represents the projects f * `agency`: [string] The agency acronym. For example "GSA" or "DOD" * `organization`: [string] The organization within the agency that the projects listed belong to. For example, "18F" or "Navy". -* `projects`: [list] Contains list of `project` objects representing each software project, as defined below. +* `projects`: [array] Contains list of `project` objects representing each software project, as defined below. ### Project JSON Object @@ -30,10 +30,10 @@ Each `project` object requires the following fields: * `name`: [string] The project name * `description`: [string] A description of the project * `license`: [`null` or string] The URL of the project license, if available. `null` should be used if not. -* `openSourceProject`: [integer] A value indicating whether or not the project is open source. +* `openSourceProject`: [number] A value indicating whether or not the project is open source. * `0`: The project is not open source. * `1`: The project is open source. -* `governmentWideReuseProject`: [integer] A value indicating whether or not the project is built for government-wide reuse. +* `governmentWideReuseProject`: [number] A value indicating whether or not the project is built for government-wide reuse. * `0`: The project is not built for government-wide reuse. * `1`: The project is built for government-wide reuse. * `tags`: [array] A list of string alphanumeric keywords that identify the project. @@ -60,7 +60,7 @@ The following `project` object fields are optional: * `twitter`: [string] The username of the project's Twitter account * `phone`: [string] The phone number to contact a project. * `partners`: [array] A list of strings containing the acronyms of agencies partnering on the project. -* `exemption`: [integer] The exemption that excuses the project from government-wide reuse. +* `exemption`: [number] The exemption that excuses the project from government-wide reuse. * `1`: The sharing of the source code is restricted by law or regulation, including—but not limited to—patent or intellectual property law, the Export Asset Regulations, the International Traffic in Arms Regulation, and the Federal laws and regulations governing classified information. * `2`: The sharing of the source code would create an identifiable risk to the detriment of national security, confidentiality of Government information, or individual privacy. * `3`: The sharing of the source code would create an identifiable risk to the stability, security, or integrity of the agency's systems or personnel.