{"id":19066712,"url":"https://github.com/washingtonpost/ans-schema","last_synced_at":"2025-04-04T16:12:35.309Z","repository":{"id":34151556,"uuid":"37989970","full_name":"washingtonpost/ans-schema","owner":"washingtonpost","description":"JSON schema definition and supporting example/validation code for The Washington Post's ANS specification","archived":false,"fork":false,"pushed_at":"2024-11-28T08:47:32.000Z","size":2934,"stargazers_count":108,"open_issues_count":20,"forks_count":44,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-03-28T15:04:51.628Z","etag":null,"topics":["arc","arc-publishing","arcxp","json-schema","schema-files","washington-post"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/washingtonpost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-24T14:35:01.000Z","updated_at":"2025-02-21T22:17:10.000Z","dependencies_parsed_at":"2023-02-10T12:31:45.117Z","dependency_job_id":"c9dcef8d-d73a-4c83-b73d-e0341eb74af9","html_url":"https://github.com/washingtonpost/ans-schema","commit_stats":{"total_commits":764,"total_committers":53,"mean_commits":"14.415094339622641","dds":0.5222513089005236,"last_synced_commit":"4e83ce4c85286ae527ebb77bc8ce402a2fdb9cbf"},"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/washingtonpost%2Fans-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/washingtonpost%2Fans-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/washingtonpost%2Fans-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/washingtonpost%2Fans-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/washingtonpost","download_url":"https://codeload.github.com/washingtonpost/ans-schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208142,"owners_count":20901570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arc","arc-publishing","arcxp","json-schema","schema-files","washington-post"],"created_at":"2024-11-09T00:57:47.300Z","updated_at":"2025-04-04T16:12:35.187Z","avatar_url":"https://github.com/washingtonpost.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ans-schema\n\nJSON schema definition and supporting example/validation code for The Washington Post's ANS specification\n\n*NOTE* This schema is in development and subject to change.\n\n# Overview\n\nANS (\"Arc Native Specification\") is the collection of schema documents that comprise the Washington Post's definition of \"content\", in so far as content is passed back and forth between systems in the Arc ecosystem of applications.\n\n## Installation\n\nWhile `ans-schema` is a public package, it does require a GitHub authentication token to be installed. First, you will need to generate a \"personal access token (classic)\" with the scope `read:packages`. Once you have the token, you can add these lines to your `~/.npmrc`:\n\n```\n@washingtonpost:registry=https://npm.pkg.github.com/\n//npm.pkg.github.com/:_authToken=ghp_XXXXXXXXXXXXXX (put your token here)\n```\n\nFinally, you can install the package:\n\n```\nnpm install @washingtonpost/ans-schema\n```\n\nFor more information, please refer to GitHub documentation:\n\n- \u003chttps://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#installing-a-package\u003e\n- \u003chttps://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages\u003e\n\n## The current production version of ANS is 0.10.10\n\n## The current development version of ANS is 0.10.11\n\n## Schema files\n\nANS Schema files are defined with the [JSON Schema specification](https://spacetelescope.github.io/understanding-json-schema/index.html).  Schemas are defined in individual files under the [src/main/resrouces/schema/ans/*version*/](src/main/resources/schema/ans/0.10.0/) directory.\n\nSmall, self-contained, attributes such as \"had copyright\" or \"had unique id\" are modeled as **traits**, which are combined together or applied directly to more complicated schema objects for the purpose of re-usability.  The \"content.json\" schema, for example, composes the traits \"credit\", \"locale\", \"location\", and \"copyright\".\n\nOne can use a variety of third party tools to validate their content against the schema files hosted here on github publicly, such as [Ajv](https://github.com/epoberezkin/ajv).\n\n## Examples\n\nA few examples are provided of content documents that validate against the Washington Post ANS schema:\n\n1. [An Example Story](tests/fixtures/schema/0.10.3/story-fixture-references.json)\n2. [An Example Video](tests/fixtures/schema/0.10.3/video-fixture-nationals.json)\n3. [An Example Image](tests/fixtures/schema/0.10.3/image-fixture-good.json)\n\n## Contributing\n\nSee the [contributing documentation](CONTRIBUTING.md) for information about how to suggest changes to the ANS schema.\n\n## Validating Locally ##\n\nThis project contains a node library that can be used to validate ANS documents locally.  It is the same validator used in the ANS Service: \u003chttp://ans.arc2.nile.works/validate/0.9.0\u003e\n\nYou can run the validator on the command line from the project directory to validate an ANS document:\n\n```\nnpm install\nnpm run-script ans -- --ansdata='{\"type\":\"story\", \"version\":\"0.8.1\"}' --version=0.10.3 validate\n\n[\n  {\n    \"keyword\": \"enum\",\n    \"dataPath\": \".version\",\n    \"schemaPath\": \"https://raw.githubusercontent.com/washingtonpost/ans-schema/master/src/main/resources/schema/ans/0.10.3/traits/trait_version.json/enum\",\n    \"params\": {},\n    \"message\": \"should be equal to one of values\"\n  }\n]\n```\n\nA file can also be used as input:\n\n```\nnpm run-script ans -- --ansfile=test.json --version=0.10.3 validate\n\n```\n\nYou can also load the validator as a library in your node project:\n\n```\nvar ans = require('@washingtonpost/ans-schema');\n\nans.getValidatorForVersion('0.10.3', function(err, validator) {\n  var errors = validator.validate({\"type\":\"story\", \"version\":\"0.5.8\"});\n\n  if (errors.length \u003e 0) {\n    console.log(\"There were some errors: \" + JSON.stringify(errors));\n  }\n  else {\n    console.log(\"It's valid!\");\n  }\n});\n```\n\n## Other Commands ##\n\n### upvert ###\n\nConverts a valid document in an old version of ANS to newer version.\n\n```\nnpm run-script ans -- --ansdata='{\"type\":\"story\", \"version\":\"0.5.0\", \"content_elements\":[{\"type\":\"text\", \"content\": \"Foo!\", \"additonal_properties\": { \"foo\":\"bar\"}}], \"taxonomy\":{\"sections\":[{ \"type\": \"section\", \"version\":\"0.5.0\"}]}}' upvert\n\n{\n  \"type\": \"story\",\n  \"version\": \"0.10.3\",\n  \"content_elements\": [\n    {\n      \"type\": \"text\",\n      \"content\": \"Foo!\",\n      \"additional_properties\": {\n        \"foo\": \"bar\"\n      }\n    }\n  ],\n  \"taxonomy\": {\n    \"sites\": [\n      {\n        \"additional_properties\": {\n          \"type\": \"section\"\n        },\n        \"version\": \"0.10.3\",\n        \"type\": \"site\",\n        \"name\": \"(unnamed)\",\n        \"primary\": false\n      }\n    ],\n    \"tags\": []\n  }\n}\n```\n\n### sync ###\n\nFixes an invalid document composed of valid sub-documents of differing ANS versions. Essentially this converts a very specific kind of invalid document to a valid one by selective upverting.\n\n```\nnpm run-script ans -- --ansdata='{\"type\":\"story\", \"version\":\"0.10.3\", \"content_elements\":[{\"type\":\"gallery\", \"version\":\"0.8.1\", \"content_elements\":[ {\"type\":\"image\", \"version\":\"0.8.1\", \"url\":\"http://foo.com/img.jpg\"}]}]}' sync\n\n{\n  \"type\": \"story\",\n  \"version\": \"0.10.3\",\n  \"content_elements\": [\n    {\n      \"type\": \"gallery\",\n      \"version\": \"0.10.3\",\n      \"content_elements\": [\n        {\n          \"type\": \"image\",\n          \"version\": \"0.10.3\",\n          \"url\": \"http://foo.com/img.jpg\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Creating a new ANS version\n\nThe script to create a new version: `npm run-script ans -- --version=x.xx.x create`\n\nAfter running this, if you've created a new major or minor version, you'll need to update line 19 in this file so that the validate endpoint will work: `lib/validator.js`.\n\nMake sure to also add a test file here: `tests/fixtures/schema/`. You can copy over the previous test file (`schema-tests-xx.js`) and rename it with your version number. When people open PRs for new schema changes, they can add tests to that file.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwashingtonpost%2Fans-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwashingtonpost%2Fans-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwashingtonpost%2Fans-schema/lists"}