origami.json (o2)

origami.json is a JSON format file that is responsible for describing various aspects of an Origami project. It is under active development and subject to change, required properties indicate those that Origami tools or services may still rely on.

The Origami specification is now deprecated. The structure of origami.json may change as Origami tooling and services are updated.

Properties

description

Type	String
Required	true

A concise description of the purpose of the project.

{
  "description": "Branded tables"
}

origamiType

Type	String or null
Required	true

Defines the type of Origami project that the manifest belongs to:

• "component" (previously module): A front-end component
• "service": An HTTP service
• "cli": A command line tool
• "library": A library that is not a front-end component
• "website": Origami websites that aren’t intended to be services
• "config": Projects that are configuration for other projects
• "example": Example and boilerplate projects
• "meta": Repository-only projects that relate to how Origami works
• null: An Origami project that does not fit any of the named categories

{
  "origamiType": "component"
}

origamiVersion

Type	Integer
Required	true

The version of the Origami specification the project follows. Note that the specification is now deprecated as of v1, any value other than 1, for example 2.0, indicates the project does not follow a specification:

{
  "origamiVersion": 1
}

brands

Type	Array
Required	false

For components which support brands, an array of one or more brands: “core”, “internal, “whitelabel”. If the brands property does not exist, this means the component is unbranded and supports all the brands.

keywords

Type	Array
Required	true

Expects keywords related to the project to help discover it in the registry.

{
  "keywords": ["table", "rows", "columns"]
}

origamiCategory

Type	String
Required	true*

*Applies to { "origamiType": "component" }.

Describes the organisational category the component belongs to:

• "utilities": Sass and JavaScript utilities that provide no markup, provide no classes and are used to encapsulate shared logic between components
• "primitives": Base components that provide minimal markup and are used by other components
• "components": Components built from primitives and utilities, which provide markup for a complete user interface
• "layouts": Complex components that provide styles for the whole page

{
  "origamiCategory": "components"
}

support

Type	String
Required	true

Describes where a user can go for support on this project, e.g. the project's GitHub issues.

{
  "support": "https://github.com/Financial-Times/o-table/issues"
}

supportStatus

Type	String
Required	true

Describes the support status of the project’s major version:

• active: feature development ongoing, bug reports will be gratefully received and acted upon promptly
• maintained: not actively developed but reproducible bugs will be fixed promptly and work done where necessary to maintain compatibility with platforms and other projects
• deprecated: not actively developed, not recommended for new projects, only the most disabling bugs will be addressed and only when time allows, but existing implementations may still work
• dead: decommissioned entirely, will receive no support
• experimental: the project is not ready for production use

{
  "supportStatus": "active"
}

supportContact

Type	Object
Required	false

Describes contact details a user can choose from to find support for this project. The owner(s) identified in the support options commit to:

• reviewing code prior to release
• signing off on deployments
• publishing and maintaining up to date releases and documentation
• decommissioning the project when appropriate
• provide support to the users of the project

The object requires two properties:

• email: type String. Is an email address that users can request support from. We recommend a group or role based email, not a named individual
• slack: type String. Is a slack channel that users can go to for support in the format: organisation/channel-name

{
  "supportContact": {
    "email": "origami.support@ft.com",
    "slack": "financialtimes/origami-support"
  }
}

browserFeatures

Type	Object
Required	false

Applies to { "origamiType": "component" }. Outlines the browser features required for the component’s functionality. The object accepts two properties:

• required: type Array. A list of features which the component assumes exists. If these features do not exist, the component may error.
• optional: type Array. A list of features which the component will use if they are available in the browser. If not the component may offer different or reduced functionality, but with graceful degradation.

{
  "origamiType": "component",
  "browserFeatures": {
    "required": ["customEvent"],
    "optional": ["IntersectionObserver", "IntersectionObserverEntry"]
  }
}

serviceUrl

Type	String
Required	true*

*Applies to { "origamiType": "service" } only.

Is the URL on which the service is provided.

{
  "origamiType": "service",
  "serviceUrl": "https://www.ft.com/__origami/service/build/"
}

demosDefaults

Type	Object
Required	false

Describes default options to be applied to all demos.

The object accepts the following properties:

• template: type String. Describes the path to the mustache template to render
• sass: type String. Describes the path to the Sass file to compile.
• js: type String. Describes the JS file to build.
• data: type Object or String. Describes data to populate to the mustache template with. If this is a string it must be a path to a JSON file containing the data, relative to the root of the repo.
• documentClasses: type String. Names CSS classes to set on the html tag.
• dependencies: type Array. Is a list of other components that are only needed for demos, which will be loaded via the Build Service

All of these properties are optional.

{
  "demosDefaults": {
    "template": "demos/src/demo.mustache"
    "sass": "demos/src/demo.scss",
    "js": "demos/src/demo.js"
    "data": {
      "striped-rows": true
    },
    "documentClasses": "demo-container",
    "dependencies": ["o-normalise"]
  }
}

demos

Type	Array
Required	false

It accepts an array. Is a list of configuration objects for individual demos. Each object in the list accepts the following properties:

required:

• name: type String. Demo name which will be used as the name of the outputted html file
• title: type String. A title for the demo which will appear when listed in the Registry
• description: type String. An explanation of the purpose of the demo
• template: type String. Describes the path to the demo-specific mustache template to render

optional:

• sass: type String. Describes the path to the demo-specific Sass file to compile.
• js: type String. Describes the path to the demo-specific JS file to build.
• data: type Object or String. Describes data to populate to the component-specific mustache template with. If this is a string it must be a path to a JSON file containing the data, relative to the root of the repo.
• brands: type Array. For components which support brands, this describes one or more brands which the demo applies to (“core”, “internal, “whitelabel”)
• documentClasses: type String. Names CSS classes to set on the component-specific html tag
• dependencies: type Array. Is a list of other components that are only needed a this specific demo, which will be loaded via the Build Service
• hidden: type Boolean. Whether the demo should be hidden in the Registry
• display_html: type Boolean. Whether the demo should have a HTML tab in the Registry (defaults to true)

{
  "demos": [
    {
      "name": "Basic table",
      "description": "Basic table implementation",
      "template": "demos/src/basic-component.mustache"
    },
    {
      "name": "Striped table",
      "description": "Striped table implementation",
      "template": "demos/src/striped-table.mustache",
      "sass": "demos/src/striped-table.scss",
      "documentClasses": "demo-striped-table-container",
      "brands": ["core", "internal"]
    },
    {
      "name": "pa11y",
      "description": "Hidden test for pa11y",
      "hidden": true,
      "template": "demos/src/pa11y.mustache"
    }
  ]
}

Example

This example joins all of the property snippets outlined above:

{
  "description": "Branded tables",
  "origamiType": "component",
  "origamiVersion": '2.0',
  "keywords": ["table", "rows", "columns"],
  "origamiCategory": "components",
  "support": "https://github.com/Financial-Times/o-table/issues",
  "supportStatus": "active",
  "supportContact": {
      "email": "origami.support@ft.com",
      "slack": "financialtimes/origami-support"
    }
  "browserFeatures": {
    "required": [
    "customEvent"
    ],
    "optional": [
      "IntersectionObserver",
      "IntersectionObserverEntry"
    ]
  },
  "demosDefaults": {
    "template": "demos/src/demo.mustache"
    "sass": "demos/src/demo.scss",
    "js": "demos/src/demo.js"
    "data": {
      "striped-rows": true
    },
    "documentClasses": "demo-container",
    "dependencies": ["o-normalise"]
  },
  "demos": [
    {
      "name": "Basic table",
      "description": "Basic table implementation",
      "template": "demos/src/basic-component.mustache"
    },
    {
      "name": "Striped table",
      "description": "Striped table implementation",
      "template": "demos/src/striped-table.mustache",
      "sass": "demos/src/striped-table.scss",
      "documentClasses": "demo-striped-table-container"
    },
    {
      "name": "pa11y",
      "description": "Hidden test for pa11y",
      "hidden": true,
      "template": "demos/src/pa11y.mustache"
    }
  ]
}