src/app/components/policy-guide/docs/compliance/compliance-inventory-code/compliance-inventory-code.template.html
<h1>Creating your enterprise code inventory</h1>
<h2>Overview</h2>
<p>Section <a
class="default-link"
pageScroll
[routerLink]="['/policy-guide/policy/implementation']"
href="#code-inventories-and-discovery">7.2</a> and <a
class="default-link"
pageScroll
[routerLink]="['/policy-guide/policy/implementation']"
href="#codegov">7.3</a> of the Source Code Policy require agencies to provide an inventory of their 'custom-developed code' to support government-wide reuse and make Federal open source code easier to find.</p>
<p>Using these inventories, <a class="default-link" href="https://Code.gov">Code.gov</a> will provide a platform to search federally funded open source software and software available for government-wide reuse.</p>
<h2>Publishing Your Agency's Inventory</h2>
<p>Agencies are required to publish their inventories using a standard metadata schema - a JSON file that they'll make available on their agency websites. Versions 1.0.0, 1.0.1, and 2.0.0. of the schema are now available. Agencies are strongly encouraged to use version 2.0.0 of the schema, which is described below. This version includes revisions that make your inventory much more useful and intuitive. Versions 1.0.0 and 1.0.1 will be phased out at the end of 2017.</p>
<p>Agencies should make the <a class="default-link" href="https://github.com/presidential-innovation-fellows/code-gov-web/blob/master/src/assets/sample_code_200.json">“code.json”</a> available in the root folder of their website (e.g., https://www.agency.gov/code.json). Code.gov will then retrieve these JSON files daily and compile them.</p>
<h2>Metadata Schema version 2.0.0</h2>
Version 2.0.0 of the <a class="default-link" href="https://github.com/presidential-innovation-fellows/code-gov-web/blob/master/src/assets/schemas/2.0.0.json">metadata schema file in JSON format can be found here.</a>
<h3>File location and contents:</h3>
<ul>
<li><code>code.json</code> must live in the root directory of your agency’s website.</li>
<li><code>code.json</code> must include a single object represented as JSON, with key-value pairs according to the list below.</li>
</ul>
<h3>Fields:</h3>
<h4>Required</h4>
<ul>
<li><code>version</code>: [string] Code.gov’s version of the metadata schema in use. Implements semantic versioning 2.0.0 rules as defined at http://semver.org. For example "2.0.0."</li>
<li><code>measurementType</code>: [object] An object containing description of the open source measurement method.
<ul>
<li><code>method</code>: [enum] An enumerated list of methods for measuring the open source requirement.
<ul>
<li><code>cost</code>: Cost of software development.</li>
<li><code>systems</code>: System certification and accreditation boundaries.</li>
<li><code>projects</code>: A complete software solution / project.</li>
<li><code>modules</code>: A self-contained module from a software solution.</li>
<li><code>linesOfCode</code>: Source lines of code.</li>
<li><code>other</code>: Another measurement method not referenced above.</li>
</ul>
</li>
</ul>
<ul>
<li><code>ifOther</code>: [string] A one- or two- sentence description of the measurement type used, if 'other' is selected as the value of 'method' field.</li>
</ul>
</li>
<li><code>agency</code>: [string] The agency acronym for Clinger Cohen Act (CCA) agencies can be found through the <a class="default-link" href="https://cfo.gov/about/">CFO Act list</a>, as CCA references the CFO Act. For example "GSA" or "DOD." Please use uppercase letters.</li>
<li><code>releases</code>: [array] Contains objects representing each versioned source code release made available.
<ul>
<li>
<code>name</code>: [string] The name of the release.
</li>
<li>
<code>repositoryURL</code>: [string] The URL of the public release repository for open source repositories. This field is not required for repositories that are only available as government-wide reuse or are closed (pursuant to one of the exemptions).
</li>
<li>
<code>description</code>: [string] A one- or two-sentence description of the release.
</li>
<li><code>permissions</code>: [object] An object containing description of the usage/restrictions regarding the release.
<ul>
<li>
<code>licenses</code>: [<code>null</code> or array of objects] An object containing license details, if available. If not, <code>null</code> should be used.
<ul>
<li><code>URL</code>: [string] The URL of the release license, if available.</li>
<li><code>name</code>: [string] An abbreviation for the name of the license. For example, 'CC0' or 'MIT.'</li>
</ul>
</li>
<li><code>usageType</code>: [enum] A list of enumerated values which describes the usage permissions for the release.
<ul>
<li><code>openSource</code>: Open source</li>
<li><code>governmentWideReuse</code>: Government-wide reuse.</li>
<li><code>exemptByLaw</code>: 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.</li>
<li><code>exemptByNationalSecurity</code>: The sharing of the source code would create an identifiable risk to the detriment of national security, confidentiality of Government information, or individual privacy.</li>
<li><code>exemptByAgencySystem</code>: The sharing of the source code would create an identifiable risk to the stability, security, or integrity of the agency’s systems or personnel.</li>
<li><code>exemptByAgencyMission</code>: The sharing of the source code would create an identifiable risk to agency mission, programs, or operations.</li>
<li><code>exemptByCIO</code>: The CIO believes it is in the national interest to exempt sharing the source code.</li>
<li><code>exemptByPolicyDate</code>: The release was created prior to the M-16-21 policy (August 8, 2016).</li>
</ul>
</li>
</ul>
<ul>
<li><code>exemptionText</code>: <code>null</code> or [string] If an exemption is listed in the 'usageType' field, this field should include a one- or two- sentence justification for the exemption used.</li>
</ul>
</li>
<li>
<code>laborHours</code>: [number] An estimate of total labor hours spent by your organization/component across all versions of this release. This includes labor performed by federal employees and contractors. See the Code.gov <a class="default-link" href="https://github.com/GSA/code-gov/blob/master/LABOR_HOUR_CALC.md">summary</a> for calculating labor hours.
</li>
<li>
<code>tags</code>: [array] An array of keywords that will be helpful in discovering and searching for the release. For example: cms, feature, image processing, tool, integration, accessibility, 508, geospatial, map, etc.
</li>
<li>
<code>contact</code>: [object] Information about contacting the release.
<ul>
<li><code>email</code>: [string] An email address to contact the release.</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Optional</h4>
<ul>
<li>Optional fields for release objects within <code>releases</code>:
<ul>
<li><code>version</code>: [string] The version for this release. For example, "1.0.0."</li>
<li><code>organization</code>: [string] The organization or component within the agency that the releases listed belong to. For example, "18F" or "Navy."</li>
<li><code>status</code>: [string] The development status of the release.
<ul>
<li><code>"Ideation"</code> - brainstorming phase.</li>
<li><code>"Development"</code> - a release is still in development.</li>
<li><code>"Alpha"</code> - initial prototyping phase and internal testing.</li>
<li><code>"Beta"</code> - a release is being tested in public.</li>
<li><code>"Release Candidate"</code> - a release is nearly ready for production.</li>
<li><code>"Production"</code> - finished release, with development and maintenance ongoing.</li>
<li><code>"Archival"</code> - finished release, but no longer actively maintained.</li>
</ul>
</li>
<li><code>vcs</code>: [string] A lowercase string with the name of the version control system that is being used for the release. For example: git, cvs, svn, mercurial, vss, etc.</li>
<li><code>homepageURL</code>: [string] The URL of the public release homepage.</li>
<li><code>downloadURL</code>: [string] The URL where a distribution of the release can be found.</li>
<li><code>disclaimerText</code>: [string] Short paragraph that includes disclaimer language to accompany the release.</li>
<li><code>disclaimerURL</code>: [string] The URL where disclaimer language regarding the release can be found.</li>
<li><code>languages</code>: [array] A list of strings with the names of the programming languages in use on the release.</li>
<li>
<code>contact</code>: [object] Information about contacting the release.
<ul>
<li><code>name</code>: [string] The name of a contact or department for the release.</li>
<li><code>URL</code>: [string] The URL to a website that can be used to reach the point of contact. For example, 'http://twitter.com/codeDotGov'.</li>
<li><code>phone</code>: [string] The phone number to contact a release.</li>
</ul>
</li>
<li><code>partners</code>: [array] An array of objects including an acronym for each agency partnering on the release and the contact email at such agency.
<ul>
<li><code>name</code>: [string] The acronym describing the partner agency.</li>
<li><code>email</code>: [string] The email address for the point of contact at the partner agency.</li>
</ul>
</li>
<li>
<code>relatedCode</code>: [array] An array of affiliated government repositories that may be a part of the same project. For example, relatedCode for 'code-gov-web' would include 'code-gov-api' and 'code-gov-tools'.
<ul>
<li><code>name</code>: [string] The name of the code repository, project, library or release.</li>
<li><code>URL</code>: [string] The URL where the code repository, project, library or release can be found.</li>
<li><code>isGovernmentRepo</code>: [boolean] True or False. Is the code repository owned or managed by a federal agency?</li>
</ul>
</li>
<li>
<code>reusedCode</code>: [array] An array of government source code, libraries, frameworks, APIs, platforms or other software used in this release. For example: US Web Design Standards, cloud.gov, Federalist, Digital Services Playbook, Analytics Reporter.
<ul>
<li><code>name</code>: [string] The name of the software used in this release.</li>
<li><code>URL</code>: [string] The URL where the software can be found.</li>
</ul>
</li>
<li><code>date</code>: [object] A date object describing the release.
<ul>
<li><code>created</code>: [string] The date the release was originally created, in YYYY-MM-DD or ISO 8601 format.</li>
<li><code>lastModified</code>: [string] The date the release was modified, in YYYY-MM-DD or ISO 8601 format.</li>
<li><code>metadataLastUpdated</code>: [string] The date the metadata of the release was last updated, in YYYY-MM-DD or ISO 8601 format.</li>
</ul>
</li>
</ul>
</li>
</ul>
<h2>Example code.json file</h2>
<p>We’ve created a <a class="default-link" href="https://github.com/presidential-innovation-fellows/code-gov-web/blob/master/src/assets/sample_code_200.json">sample code.json</a>.</p>
<h2>Tools</h2>
<ul>
<li>
<a
class="default-link"
routerLink="/policy-guide/docs/compliance/inventory-code/tools/validate-schema"
>
Schema Validator
</a>
<p>
A tool for validating your code.json against either the v1.0.1 or v2.0.0 schemas. After entering
in your code.json, it will list and highlight issues and provide a full featured code editor for
making changes to the file.
</p>
</li>
<li>
<a
class="default-link"
routerLink="/policy-guide/docs/compliance/inventory-code/tools/upgrade-schema"
>
v1.0.1 to v2.0.0 Schema Upgrader
</a>
<p>
The upgrader takes a valid v1.0.1 code.json and performs as many automatic upgrades as it can. It
also adds additional fields to the JSON to serve as templates for adding more information about
your repositories.
</p>
</li>
</ul>
<h2><a
class="default-link"
href="https://github.com/presidential-innovation-fellows/code-gov-web/blob/master/CHANGELOG.md"
>Changelog</a></h2>
<h3>August 2017 - Version 2.0.0</h3>
<p>This revision includes revisions to incorporate the open source measurement requirement, improvements and clarifications on previous versions of schema content.</p>
<h4 id="added">Added</h4>
<ul>
<li>'openSourceMeasureType' - The source code policy requires that 20% of an agency's code inventory must be made available as open-source. In order to do so, agencies must (1) identify a method for measuring the 20% metric and (2) apply the measurement method to the total enterprise code inventory to establish a baseline. </li>
<li>Start using "changelog.md" to track changes to the official schema file.</li>
<li>'permissions' - includes details about usage/licensing, replaces the openSourceProject/governmentWideReuseProject.</li>
<li>'measurementType' - agencies can choose from a list of enumerated descriptions of how they measure the 20% requirement.</li>
<li>'disclaimerText' - includes short, paragraph-long disclaimer language.</li>
<li>'disclaimerURL' - link to disclaimer language.</li>
<li>'laborHours' - number of hours involved in building the release.</li>
<li>'relatedCode' - array of related source code repositories.</li>
<li>'reusedCode' - array of government software used in the release.</li>
<li>'version' - added versioning to releases </li>
</ul>
<h4 id="changed">Changed</h4>
<ul>
<li>'releases' - changed from 'projects' to reflect types of repositories that should be listed.</li>
<li>'licenses' - changed license from a URL string to an object which includes a URL and a name.
<ul>
<li>'repositoryURL' - changed from 'repository' for consistency. </li>
<li>'homepageURL' - changed from 'homepage' for consistency.</li>
<li>'exemptionText' - now included within the 'permissions' object.</li>
<li>'date' - changed from 'updated' object; removed metadataLastUpdated, lastCommit, and sourceCodeLastModified and replaced with created, lastModified, and metadataLastUpdated</li></ul>
</li>
</ul>
<h4 id="removed">Removed</h4>
<ul>
<li>'openSourceProject'</li>
<li>'governmentWideReuseProject' </li>
<li>'exemption' - now included within the enumerated usageType options in the 'permissions' object.</li>
</ul>
<h3>December 2016 - Version 1.0.1</h3>
<p>This revision includes minor tweaks that are aimed at clarifying certain fields and increasing the overall utility of the schema content.</p>
<h4>Changes in v1.0.1</h4>
<ul>
<li>'version': The first official iteration of the code.gov metadata schema will be version 1.0.1. Adding a version number to the schema makes it easier to track and manage changes between versions of the metadata schema.</li>
<li>‘organization’: The ‘organization’ field, which holds the name of the sub-agency responsible for a particular repository or release, is now optional. It has also been moved into the ‘releases’ object. This enables agencies to identify the appropriate organization that owns the repository within the agency.</li>
<li>‘releases’: This guide previously referred to a ‘release’ field in the metadata schema, while the sample code.json referred to the plural form ‘releases’. This guide has been updated to refer to the plural form ‘releases’.</li>
<li>‘repository’: The link to the open source repository will be considered a required field for all open source repositories. For repositories that are only available as government-wide reuse or are closed, pursuant to one of the exemptions, this field is not required.</li>
<li>‘exemptionText’: This field allows agencies to provide a brief narrative explanation for the exception requested in the 'exemption' field.</li>
</ul>