Skip to content

Product Form Features v4

Sub-resource of products for the physical and digital characteristics of a product's formats: the colour of a hardback's page edges, the version of EPUB an e-book is built to, the hazard warnings a boxed set has to carry, the paper certification of a printed edition, and the accessibility properties of an e-book, which carry the most documented detail here.

Each record pairs a characteristic (type, a code from Codelist 79) with the coded answer to it (value), optionally qualified by free text (description). A feature is always a statement about one of the product's formats rather than about the product as a whole, and product_type names that format.


Endpoints


GET /resource/v4/products/{product_id}/form_features

List Product Form Features

Description

Returns the form features of the product, paginated (100 per page by default) with the standard page, page_size and legacy display parameters (see Resource Queries). The payload is the {_links, _pagination, items} envelope.

Records are always returned in _id order, which is creation order. A sort parameter is accepted but has no effect. Features therefore do not arrive grouped by type — a product whose accessibility codes were written in two batches returns them interleaved.

Only two fields are filterable: type and product_type. Any other field name — value, description, _id — is rejected with 400 Bad Request naming the offending parameter. On those two fields the scalar operators apply; see Resource Queries. Comparison is case-insensitive, so ?product_type=EBOOK and ?product_type=ebook are equivalent.

Useful queries:

  • ?type=09 — the accessibility declaration only.
  • ?type=12 — hazard warnings only.
  • ?type__ne=09 — everything except accessibility.
  • ?product_type=book — features of the printed edition only.

Input parameters

Path parameters

Parameter Type Default Nullable Description
product_id string No UUID of the product.

Query parameters

Parameter Type Default Nullable Description
product_type string No Filter by the format the feature describes: `ebook`, `book`, `audiobook` or `nonbook`. Matched case-insensitively.
type string No Filter by product form feature type ([Codelist 79](https://ns.editeur.org/onix/en/79)) — e.g. `09` for accessibility details, `12` for hazard warnings. Supports the scalar operators; see [Resource Queries](/resource_queries/).

Responses

{
    "_links": {
        "first": "https://api.openpublishing.com/resource/v4/products/e86581a9-e616-11ee-a221-00505699575c/form_features?page=1&page_size=100",
        "last": "https://api.openpublishing.com/resource/v4/products/e86581a9-e616-11ee-a221-00505699575c/form_features?page=1&page_size=100",
        "next": null,
        "prev": null,
        "self": "https://api.openpublishing.com/resource/v4/products/e86581a9-e616-11ee-a221-00505699575c/form_features?page_size=100"
    },
    "_pagination": {
        "page": 1,
        "page_size": 100,
        "total": 3
    },
    "items": [
        {
            "_id": 1520172,
            "description": null,
            "product_type": "ebook",
            "type": "09",
            "value": "04"
        },
        {
            "_id": 1142597,
            "description": null,
            "product_type": "ebook",
            "type": "09",
            "value": "11"
        },
        {
            "_id": 1142601,
            "description": null,
            "product_type": "ebook",
            "type": "12",
            "value": "00"
        }
    ]
}
Schema of the response body
{
    "type": "array",
    "items": {
        "type": "object",
        "description": "One characteristic of one of a product's formats, as an ONIX 3 ProductFormFeature composite.",
        "properties": {
            "_id": {
                "type": "string",
                "description": "Identifier of the feature record, and the value to use as the `{feature_id}` path\nsegment.\n\n**This is a legacy integer, not a UUID.** Although the schema declares `string`, the\nvalue arrives as a JSON number such as `1142596` — unquoted — and a client must be\nprepared to read it as a number. The v4 response for this sub-resource is\nbyte-identical to the v3 one: unlike prices, titles or files, form features carry no\n`_legacy_id`, no `_version` and no per-item `_links`. A UUID does also resolve as the\n`{feature_id}` path segment, but the API never returns one, so this integer is the only\nidentifier an integration can obtain and use.\n\nThe list response likewise arrives as the paginated\n`{_links, _pagination, items}` envelope rather than as the bare array the `200` schema\ndeclares.\n",
                "example": 1142596
            },
            "product_type": {
                "type": "string",
                "description": "Which of the product's formats this feature describes. A single product carries\nall of its editions at once — the printed book, the e-book, the audiobook — so a\nfeature that is true of the e-book is not automatically true of the hardback, and every\nrecord names its format explicitly. Filtering by `product_type` selects what is true of\none edition.\n\nFour formats are accepted:\n\n- `ebook` — the e-book edition (EPUB, PDF, Kindle). Carries the accessibility (`09`),\n  hazard-warning (`12`) and format-version (`15`) features.\n- `book` — the printed edition. Carries the physical features — binding and page-edge\n  colours and paper certification.\n- `audiobook` — the audiobook edition.\n- `nonbook` — a non-book product such as a game or merchandise.\n\nThree legacy aliases also resolve to `ebook`:\n\n- `epub`\n- `mobi`\n- `ibooks`\n\nThe value is matched case-insensitively on write and always returned lowercase, so\n`EBOOK`, `Ebook` and `ebook` are one value. Anything else — including the platform's\nnon-publication product types such as `service`, `fee` or `shipment` — is rejected with\n`400 Bad Request`.\n\nFilterable — `?product_type=ebook`. See [Resource Queries](/resource_queries/).\n",
                "example": "ebook",
                "x-enum-descriptions": {
                    "ebook": "E-book edition (EPUB, PDF, Kindle). Carries accessibility (`type` `09`), hazard warnings (`12`) and format-version (`15`) features.",
                    "book": "Printed edition. Carries the physical features — binding and page-edge colours and paper certification.",
                    "audiobook": "Audiobook edition.",
                    "nonbook": "Non-book product such as a game or merchandise."
                }
            },
            "type": {
                "type": "string",
                "description": "The characteristic being described: a code from\n[Codelist 79](https://ns.editeur.org/onix/en/79). All 59 codes of the ONIX 3.1\nrevision of that list are accepted — the list is not contiguous, and `11`, `28` and\n`29` are not among them — and an unrecognised code is rejected with `400 Bad Request`.\n\n`type` is half of a pair: it decides which vocabulary `value` must come from. There is\nno single list of legal values, and only two pairings are checked on write; see `value`.\n\nThe list groups into families. Broadly:\n\n- **Physical make-up of a printed book** — `01` colour of cover, `26` colour of spine,\n  `02` colour of page edges, `55` endpapers, `57` ribbon marker(s), `58` head and tail\n  bands, `27`/`59` foil on cover/jacket, `03` text font, `04` special cover material.\n- **Digital publications** — `09` e-publication accessibility detail, `10`/`15`/`16`\n  e-publication format version (free text / coded / validator version), `18`\n  authentication and access control, `06`/`07` operating-system and other system\n  requirements.\n- **Product safety** — `12` US CPSIA or other international hazard warning, `13` EU\n  General Product Safety Regulation / Toy Safety Directive warning, `14` IATA dangerous\n  goods, `19`–`21` batteries and dangerous goods, `25` personal data requirements.\n- **Paper and carbon certification** — `30`–`40` FSC / PEFC / recycled content / \"green\"\n  inks and adhesives, `41`–`46` carbon and greenhouse-gas certification.\n- **Raw-material sourcing** — `47`–`54`, `56` and `60`–`62`. Accepted values whose\n  meanings are defined by Codelist 79; nothing here interprets them.\n\n**Three of these types are treated specially**; for the rest `value` is returned exactly\nas it was supplied and is not interpreted:\n\n- `09` **E-publication accessibility detail** — `value` is validated against\n  [Codelist 196](https://ns.editeur.org/onix/en/196).\n- `12` **US CPSIA or other international hazard warning** — `value` is validated\n  against [Codelist 143](https://ns.editeur.org/onix/en/143).\n- `15` **E-publication format version code** — records which EPUB, PDF or Kindle\n  version a file is, using [Codelist 220](https://ns.editeur.org/onix/en/220).\n  Incomplete when written here; see `value`.\n\nFor every other code, `value` is accepted verbatim with no validation at all — a colour\nname, a percentage, a URL, or a code belonging to a codelist other than the one ONIX\nnominates for that type. Nothing reports such a value as wrong.\n\nAccessibility and hazard-warning features are also seeded from the realm's configured\ndefaults when a product is first initialised, so a product can already carry `09` and\n`12` records that no client created:\n\n- Codelist 196 codes seeded as `09` features on the **e-book only**, together with the\n  text of a `00` summary record where one is configured.\n- Codelist 143 codes seeded as `12` features, separately configurable for the e-book and\n  for the printed book.\n\nSeeding runs when a product is first initialised, which is not the same event as\n`POST /resource/v4/products`: that endpoint creates a product without defaults.\n\nFilterable — `?type=09`, `?type__ne=09`. See\n[Resource Queries](/resource_queries/).\n",
                "example": "09"
            },
            "value": {
                "type": "string",
                "description": "The coded answer to the characteristic in `type`. Its permitted vocabulary is decided by\n`type`, so \"valid\" here is not a fixed list.\n\nThe same `type` may legitimately appear many times on one product with different\nvalues — that is how an e-book declares a list of accessibility properties. Only the\nwhole combination should be unique, and nothing here enforces even that.\n\n**`type: \"09\"` — accessibility.** `value` must be a code from\n[Codelist 196](https://ns.editeur.org/onix/en/196); anything else is rejected with\n`400 Bad Request`. An e-book declares its accessibility by carrying *one record per\nproperty*, not one record with a list. The codes fall into four uses.\n\nBlanket statements:\n\n- `08` — unknown accessibility\n- `09` — inaccessible, or known limited accessibility\n\n`08` is a common seeded default on a new e-book, and it means \"not yet assessed\", not\n\"accessible\". Nothing prevents `08` from coexisting with a detailed declaration; where\nboth are present, the detailed codes are the more specific statement.\n\nConformance claims:\n\n- `01` — LIA compliance scheme\n- `02` — EPUB Accessibility Specification 1.0 A\n- `03` — EPUB Accessibility Specification 1.0 AA\n- `04` — EPUB Accessibility Specification 1.1\n- `05` — PDF/UA-1\n- `06` — PDF/UA-2\n- `80`, `81`, `82` — WCAG 2.0, 2.1, 2.2\n- `84`, `85`, `86` — WCAG level A, AA, AAA\n\nIndividual accessibility properties, the substance of a European Accessibility Act\ndeclaration:\n\n- `10` — no reading-system accessibility options actively disabled\n- `11` — table of contents navigation\n- `12` — index navigation\n- `13` — single logical reading order\n- `14` — short alternative textual descriptions\n- `15` — full alternative textual descriptions\n- `19` — print-equivalent page numbering\n- `20` — synchronised pre-recorded audio\n- `21` — text-to-speech hinting provided\n- `22` — language tagging provided\n- `24` — dyslexia readability\n- `25` — use of colour is not the sole means of conveying information\n- `26` — high contrast between text and background\n- `29` — next / previous structural navigation\n- `30` — ARIA roles provided\n- `32` — landmark navigation\n- `36` — appearance of all textual content can be modified\n- `37` — ultra-high contrast between text and background\n- `41` — page-list navigation\n- `52` — all non-decorative content supports reading without sight\n\nExceptions and contact points:\n\n- `75`, `76`, `77` — EAA exceptions: micro-enterprise, disproportionate burden,\n  fundamental alteration\n- `94` — compliance web page for detailed accessibility information\n- `96` — publisher's web page for detailed accessibility information\n- `99` — publisher contact for further accessibility information\n- `00` — accessibility summary\n\nThe last two put their real payload in `description` rather than in `value`; see\n`description`.\n\n**`type: \"12\"` — hazard warnings.** `value` must be a code from\n[Codelist 143](https://ns.editeur.org/onix/en/143), otherwise `400 Bad Request`. `00`\nmeans *no known hazards or warnings* — an explicit \"this was checked and there is\nnothing\", which is not the same as omitting the feature. The remaining 23 codes are the\nCPSIA choking, strangulation, magnet, flashing, sound and motion-simulation warnings,\ntheir \"no warning necessary\" counterparts, and the California Proposition 65 warnings.\n\n**`type: \"15\"` — e-publication format version.** ONIX expects a\n[Codelist 220](https://ns.editeur.org/onix/en/220) version code here:\n\n- `101A`–`101F` — EPUB 2.0.1, 3.0, 3.0.1, 3.1, 3.2, 3.3\n- `107C`, `107D`, `107G`, `107J` — PDF 1.3, 1.4, 1.7, 2.0\n- `116A`, `116B`, `116C` — Kindle MOBI 7, KF8, KFX\n\n**This endpoint does not validate `value` for `type` `15`**: any value at all is\naccepted, including one that is not a Codelist 220 code. A `15` feature also has to name\nthe specific e-book file format it applies to (EPUB, PDF, Mobipocket, iBooks), and that\ncannot be supplied through this endpoint, so a `15` feature created here is incomplete.\n\n**Every other `type`.** No validation, and the value is whatever the ONIX definition of\nthat type calls for — a colour name for `01`/`02`/`26`, a percentage for `36`/`37`, a\nURL for `43`, or an empty string where the presence of the code is itself the whole\nstatement. A very long value is silently truncated rather than rejected.\n\nNot filterable: only `type` and `product_type` are.\n",
                "example": "10"
            },
            "description": {
                "type": "string",
                "nullable": true,
                "description": "Free-text qualifier for the cases where the code in `value` is not enough on its own.\n`null` whenever it is unset, which is the usual state.\n\nIt carries the substance of the record for exactly two accessibility codes:\n\n- **`type: \"09\"`, `value: \"00\"`** (accessibility summary) — `value` is only a marker;\n  the prose summary itself, or a URL pointing to one, lives here. A new title can be\n  seeded with a house default from the realm's configuration.\n- **`type: \"09\"`, `value: \"99\"`** (publisher contact for further accessibility\n  information) — the contact address belongs here. Nothing on the write path requires\n  it: a `99` record with an empty `description` is accepted as readily as a complete\n  one.\n\nAn explicit `null` clears the field; omitting the key on a `PUT` leaves it unchanged. A\nvery long value is silently truncated rather than rejected.\n",
                "example": null
            }
        },
        "required": [
            "type",
            "value",
            "product_type"
        ]
    }
}

POST /resource/v4/products/{product_id}/form_features

Create a Product Form Feature

Description

Adds one feature to the product. There is no bulk endpoint: an accessibility declaration of twelve properties is twelve POSTs.

product_type, type and value must all be present. A missing field is not reported as a missing field: a body with a valid product_type but no type comes back as 400 Bad Request reporting an invalid type of "".

Validation applied on write, in order — every failure is a 400 Bad Request:

  1. product_type must resolve to one of the four publishable formats. Both an unrecognised string and a product type that is not publishable (service, fee, shipment, print_author, reviewers_copy, …) are rejected.
  2. type must be a Codelist 79 code.
  3. value is checked only for type 09 (against Codelist 196) and type 12 (against Codelist 143). For every other type — including 15value is accepted unchecked.

Nothing rejects a duplicate (same product_type, type and value), even though only the whole combination is meaningful.

The example below adds "landmark navigation" to an e-book's accessibility declaration.

Input parameters

Path parameters

Parameter Type Default Nullable Description
product_id string No UUID of the product.

Request body

{
    "product_type": "ebook",
    "type": "09",
    "value": "32",
    "description": null
}
Schema of the request body
{
    "type": "object",
    "description": "One characteristic of one of a product's formats, as an ONIX 3 ProductFormFeature composite.",
    "properties": {
        "_id": {
            "type": "string",
            "description": "Identifier of the feature record, and the value to use as the `{feature_id}` path\nsegment.\n\n**This is a legacy integer, not a UUID.** Although the schema declares `string`, the\nvalue arrives as a JSON number such as `1142596` — unquoted — and a client must be\nprepared to read it as a number. The v4 response for this sub-resource is\nbyte-identical to the v3 one: unlike prices, titles or files, form features carry no\n`_legacy_id`, no `_version` and no per-item `_links`. A UUID does also resolve as the\n`{feature_id}` path segment, but the API never returns one, so this integer is the only\nidentifier an integration can obtain and use.\n\nThe list response likewise arrives as the paginated\n`{_links, _pagination, items}` envelope rather than as the bare array the `200` schema\ndeclares.\n",
            "example": 1142596
        },
        "product_type": {
            "type": "string",
            "description": "Which of the product's formats this feature describes. A single product carries\nall of its editions at once — the printed book, the e-book, the audiobook — so a\nfeature that is true of the e-book is not automatically true of the hardback, and every\nrecord names its format explicitly. Filtering by `product_type` selects what is true of\none edition.\n\nFour formats are accepted:\n\n- `ebook` — the e-book edition (EPUB, PDF, Kindle). Carries the accessibility (`09`),\n  hazard-warning (`12`) and format-version (`15`) features.\n- `book` — the printed edition. Carries the physical features — binding and page-edge\n  colours and paper certification.\n- `audiobook` — the audiobook edition.\n- `nonbook` — a non-book product such as a game or merchandise.\n\nThree legacy aliases also resolve to `ebook`:\n\n- `epub`\n- `mobi`\n- `ibooks`\n\nThe value is matched case-insensitively on write and always returned lowercase, so\n`EBOOK`, `Ebook` and `ebook` are one value. Anything else — including the platform's\nnon-publication product types such as `service`, `fee` or `shipment` — is rejected with\n`400 Bad Request`.\n\nFilterable — `?product_type=ebook`. See [Resource Queries](/resource_queries/).\n",
            "example": "ebook",
            "x-enum-descriptions": {
                "ebook": "E-book edition (EPUB, PDF, Kindle). Carries accessibility (`type` `09`), hazard warnings (`12`) and format-version (`15`) features.",
                "book": "Printed edition. Carries the physical features — binding and page-edge colours and paper certification.",
                "audiobook": "Audiobook edition.",
                "nonbook": "Non-book product such as a game or merchandise."
            }
        },
        "type": {
            "type": "string",
            "description": "The characteristic being described: a code from\n[Codelist 79](https://ns.editeur.org/onix/en/79). All 59 codes of the ONIX 3.1\nrevision of that list are accepted — the list is not contiguous, and `11`, `28` and\n`29` are not among them — and an unrecognised code is rejected with `400 Bad Request`.\n\n`type` is half of a pair: it decides which vocabulary `value` must come from. There is\nno single list of legal values, and only two pairings are checked on write; see `value`.\n\nThe list groups into families. Broadly:\n\n- **Physical make-up of a printed book** — `01` colour of cover, `26` colour of spine,\n  `02` colour of page edges, `55` endpapers, `57` ribbon marker(s), `58` head and tail\n  bands, `27`/`59` foil on cover/jacket, `03` text font, `04` special cover material.\n- **Digital publications** — `09` e-publication accessibility detail, `10`/`15`/`16`\n  e-publication format version (free text / coded / validator version), `18`\n  authentication and access control, `06`/`07` operating-system and other system\n  requirements.\n- **Product safety** — `12` US CPSIA or other international hazard warning, `13` EU\n  General Product Safety Regulation / Toy Safety Directive warning, `14` IATA dangerous\n  goods, `19`–`21` batteries and dangerous goods, `25` personal data requirements.\n- **Paper and carbon certification** — `30`–`40` FSC / PEFC / recycled content / \"green\"\n  inks and adhesives, `41`–`46` carbon and greenhouse-gas certification.\n- **Raw-material sourcing** — `47`–`54`, `56` and `60`–`62`. Accepted values whose\n  meanings are defined by Codelist 79; nothing here interprets them.\n\n**Three of these types are treated specially**; for the rest `value` is returned exactly\nas it was supplied and is not interpreted:\n\n- `09` **E-publication accessibility detail** — `value` is validated against\n  [Codelist 196](https://ns.editeur.org/onix/en/196).\n- `12` **US CPSIA or other international hazard warning** — `value` is validated\n  against [Codelist 143](https://ns.editeur.org/onix/en/143).\n- `15` **E-publication format version code** — records which EPUB, PDF or Kindle\n  version a file is, using [Codelist 220](https://ns.editeur.org/onix/en/220).\n  Incomplete when written here; see `value`.\n\nFor every other code, `value` is accepted verbatim with no validation at all — a colour\nname, a percentage, a URL, or a code belonging to a codelist other than the one ONIX\nnominates for that type. Nothing reports such a value as wrong.\n\nAccessibility and hazard-warning features are also seeded from the realm's configured\ndefaults when a product is first initialised, so a product can already carry `09` and\n`12` records that no client created:\n\n- Codelist 196 codes seeded as `09` features on the **e-book only**, together with the\n  text of a `00` summary record where one is configured.\n- Codelist 143 codes seeded as `12` features, separately configurable for the e-book and\n  for the printed book.\n\nSeeding runs when a product is first initialised, which is not the same event as\n`POST /resource/v4/products`: that endpoint creates a product without defaults.\n\nFilterable — `?type=09`, `?type__ne=09`. See\n[Resource Queries](/resource_queries/).\n",
            "example": "09"
        },
        "value": {
            "type": "string",
            "description": "The coded answer to the characteristic in `type`. Its permitted vocabulary is decided by\n`type`, so \"valid\" here is not a fixed list.\n\nThe same `type` may legitimately appear many times on one product with different\nvalues — that is how an e-book declares a list of accessibility properties. Only the\nwhole combination should be unique, and nothing here enforces even that.\n\n**`type: \"09\"` — accessibility.** `value` must be a code from\n[Codelist 196](https://ns.editeur.org/onix/en/196); anything else is rejected with\n`400 Bad Request`. An e-book declares its accessibility by carrying *one record per\nproperty*, not one record with a list. The codes fall into four uses.\n\nBlanket statements:\n\n- `08` — unknown accessibility\n- `09` — inaccessible, or known limited accessibility\n\n`08` is a common seeded default on a new e-book, and it means \"not yet assessed\", not\n\"accessible\". Nothing prevents `08` from coexisting with a detailed declaration; where\nboth are present, the detailed codes are the more specific statement.\n\nConformance claims:\n\n- `01` — LIA compliance scheme\n- `02` — EPUB Accessibility Specification 1.0 A\n- `03` — EPUB Accessibility Specification 1.0 AA\n- `04` — EPUB Accessibility Specification 1.1\n- `05` — PDF/UA-1\n- `06` — PDF/UA-2\n- `80`, `81`, `82` — WCAG 2.0, 2.1, 2.2\n- `84`, `85`, `86` — WCAG level A, AA, AAA\n\nIndividual accessibility properties, the substance of a European Accessibility Act\ndeclaration:\n\n- `10` — no reading-system accessibility options actively disabled\n- `11` — table of contents navigation\n- `12` — index navigation\n- `13` — single logical reading order\n- `14` — short alternative textual descriptions\n- `15` — full alternative textual descriptions\n- `19` — print-equivalent page numbering\n- `20` — synchronised pre-recorded audio\n- `21` — text-to-speech hinting provided\n- `22` — language tagging provided\n- `24` — dyslexia readability\n- `25` — use of colour is not the sole means of conveying information\n- `26` — high contrast between text and background\n- `29` — next / previous structural navigation\n- `30` — ARIA roles provided\n- `32` — landmark navigation\n- `36` — appearance of all textual content can be modified\n- `37` — ultra-high contrast between text and background\n- `41` — page-list navigation\n- `52` — all non-decorative content supports reading without sight\n\nExceptions and contact points:\n\n- `75`, `76`, `77` — EAA exceptions: micro-enterprise, disproportionate burden,\n  fundamental alteration\n- `94` — compliance web page for detailed accessibility information\n- `96` — publisher's web page for detailed accessibility information\n- `99` — publisher contact for further accessibility information\n- `00` — accessibility summary\n\nThe last two put their real payload in `description` rather than in `value`; see\n`description`.\n\n**`type: \"12\"` — hazard warnings.** `value` must be a code from\n[Codelist 143](https://ns.editeur.org/onix/en/143), otherwise `400 Bad Request`. `00`\nmeans *no known hazards or warnings* — an explicit \"this was checked and there is\nnothing\", which is not the same as omitting the feature. The remaining 23 codes are the\nCPSIA choking, strangulation, magnet, flashing, sound and motion-simulation warnings,\ntheir \"no warning necessary\" counterparts, and the California Proposition 65 warnings.\n\n**`type: \"15\"` — e-publication format version.** ONIX expects a\n[Codelist 220](https://ns.editeur.org/onix/en/220) version code here:\n\n- `101A`–`101F` — EPUB 2.0.1, 3.0, 3.0.1, 3.1, 3.2, 3.3\n- `107C`, `107D`, `107G`, `107J` — PDF 1.3, 1.4, 1.7, 2.0\n- `116A`, `116B`, `116C` — Kindle MOBI 7, KF8, KFX\n\n**This endpoint does not validate `value` for `type` `15`**: any value at all is\naccepted, including one that is not a Codelist 220 code. A `15` feature also has to name\nthe specific e-book file format it applies to (EPUB, PDF, Mobipocket, iBooks), and that\ncannot be supplied through this endpoint, so a `15` feature created here is incomplete.\n\n**Every other `type`.** No validation, and the value is whatever the ONIX definition of\nthat type calls for — a colour name for `01`/`02`/`26`, a percentage for `36`/`37`, a\nURL for `43`, or an empty string where the presence of the code is itself the whole\nstatement. A very long value is silently truncated rather than rejected.\n\nNot filterable: only `type` and `product_type` are.\n",
            "example": "10"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free-text qualifier for the cases where the code in `value` is not enough on its own.\n`null` whenever it is unset, which is the usual state.\n\nIt carries the substance of the record for exactly two accessibility codes:\n\n- **`type: \"09\"`, `value: \"00\"`** (accessibility summary) — `value` is only a marker;\n  the prose summary itself, or a URL pointing to one, lives here. A new title can be\n  seeded with a house default from the realm's configuration.\n- **`type: \"09\"`, `value: \"99\"`** (publisher contact for further accessibility\n  information) — the contact address belongs here. Nothing on the write path requires\n  it: a `99` record with an empty `description` is accepted as readily as a complete\n  one.\n\nAn explicit `null` clears the field; omitting the key on a `PUT` leaves it unchanged. A\nvery long value is silently truncated rather than rejected.\n",
            "example": null
        }
    },
    "required": [
        "type",
        "value",
        "product_type"
    ]
}

Responses

{
    "_id": 1520176,
    "description": null,
    "product_type": "ebook",
    "type": "09",
    "value": "32"
}
Schema of the response body
{
    "type": "object",
    "description": "One characteristic of one of a product's formats, as an ONIX 3 ProductFormFeature composite.",
    "properties": {
        "_id": {
            "type": "string",
            "description": "Identifier of the feature record, and the value to use as the `{feature_id}` path\nsegment.\n\n**This is a legacy integer, not a UUID.** Although the schema declares `string`, the\nvalue arrives as a JSON number such as `1142596` — unquoted — and a client must be\nprepared to read it as a number. The v4 response for this sub-resource is\nbyte-identical to the v3 one: unlike prices, titles or files, form features carry no\n`_legacy_id`, no `_version` and no per-item `_links`. A UUID does also resolve as the\n`{feature_id}` path segment, but the API never returns one, so this integer is the only\nidentifier an integration can obtain and use.\n\nThe list response likewise arrives as the paginated\n`{_links, _pagination, items}` envelope rather than as the bare array the `200` schema\ndeclares.\n",
            "example": 1142596
        },
        "product_type": {
            "type": "string",
            "description": "Which of the product's formats this feature describes. A single product carries\nall of its editions at once — the printed book, the e-book, the audiobook — so a\nfeature that is true of the e-book is not automatically true of the hardback, and every\nrecord names its format explicitly. Filtering by `product_type` selects what is true of\none edition.\n\nFour formats are accepted:\n\n- `ebook` — the e-book edition (EPUB, PDF, Kindle). Carries the accessibility (`09`),\n  hazard-warning (`12`) and format-version (`15`) features.\n- `book` — the printed edition. Carries the physical features — binding and page-edge\n  colours and paper certification.\n- `audiobook` — the audiobook edition.\n- `nonbook` — a non-book product such as a game or merchandise.\n\nThree legacy aliases also resolve to `ebook`:\n\n- `epub`\n- `mobi`\n- `ibooks`\n\nThe value is matched case-insensitively on write and always returned lowercase, so\n`EBOOK`, `Ebook` and `ebook` are one value. Anything else — including the platform's\nnon-publication product types such as `service`, `fee` or `shipment` — is rejected with\n`400 Bad Request`.\n\nFilterable — `?product_type=ebook`. See [Resource Queries](/resource_queries/).\n",
            "example": "ebook",
            "x-enum-descriptions": {
                "ebook": "E-book edition (EPUB, PDF, Kindle). Carries accessibility (`type` `09`), hazard warnings (`12`) and format-version (`15`) features.",
                "book": "Printed edition. Carries the physical features — binding and page-edge colours and paper certification.",
                "audiobook": "Audiobook edition.",
                "nonbook": "Non-book product such as a game or merchandise."
            }
        },
        "type": {
            "type": "string",
            "description": "The characteristic being described: a code from\n[Codelist 79](https://ns.editeur.org/onix/en/79). All 59 codes of the ONIX 3.1\nrevision of that list are accepted — the list is not contiguous, and `11`, `28` and\n`29` are not among them — and an unrecognised code is rejected with `400 Bad Request`.\n\n`type` is half of a pair: it decides which vocabulary `value` must come from. There is\nno single list of legal values, and only two pairings are checked on write; see `value`.\n\nThe list groups into families. Broadly:\n\n- **Physical make-up of a printed book** — `01` colour of cover, `26` colour of spine,\n  `02` colour of page edges, `55` endpapers, `57` ribbon marker(s), `58` head and tail\n  bands, `27`/`59` foil on cover/jacket, `03` text font, `04` special cover material.\n- **Digital publications** — `09` e-publication accessibility detail, `10`/`15`/`16`\n  e-publication format version (free text / coded / validator version), `18`\n  authentication and access control, `06`/`07` operating-system and other system\n  requirements.\n- **Product safety** — `12` US CPSIA or other international hazard warning, `13` EU\n  General Product Safety Regulation / Toy Safety Directive warning, `14` IATA dangerous\n  goods, `19`–`21` batteries and dangerous goods, `25` personal data requirements.\n- **Paper and carbon certification** — `30`–`40` FSC / PEFC / recycled content / \"green\"\n  inks and adhesives, `41`–`46` carbon and greenhouse-gas certification.\n- **Raw-material sourcing** — `47`–`54`, `56` and `60`–`62`. Accepted values whose\n  meanings are defined by Codelist 79; nothing here interprets them.\n\n**Three of these types are treated specially**; for the rest `value` is returned exactly\nas it was supplied and is not interpreted:\n\n- `09` **E-publication accessibility detail** — `value` is validated against\n  [Codelist 196](https://ns.editeur.org/onix/en/196).\n- `12` **US CPSIA or other international hazard warning** — `value` is validated\n  against [Codelist 143](https://ns.editeur.org/onix/en/143).\n- `15` **E-publication format version code** — records which EPUB, PDF or Kindle\n  version a file is, using [Codelist 220](https://ns.editeur.org/onix/en/220).\n  Incomplete when written here; see `value`.\n\nFor every other code, `value` is accepted verbatim with no validation at all — a colour\nname, a percentage, a URL, or a code belonging to a codelist other than the one ONIX\nnominates for that type. Nothing reports such a value as wrong.\n\nAccessibility and hazard-warning features are also seeded from the realm's configured\ndefaults when a product is first initialised, so a product can already carry `09` and\n`12` records that no client created:\n\n- Codelist 196 codes seeded as `09` features on the **e-book only**, together with the\n  text of a `00` summary record where one is configured.\n- Codelist 143 codes seeded as `12` features, separately configurable for the e-book and\n  for the printed book.\n\nSeeding runs when a product is first initialised, which is not the same event as\n`POST /resource/v4/products`: that endpoint creates a product without defaults.\n\nFilterable — `?type=09`, `?type__ne=09`. See\n[Resource Queries](/resource_queries/).\n",
            "example": "09"
        },
        "value": {
            "type": "string",
            "description": "The coded answer to the characteristic in `type`. Its permitted vocabulary is decided by\n`type`, so \"valid\" here is not a fixed list.\n\nThe same `type` may legitimately appear many times on one product with different\nvalues — that is how an e-book declares a list of accessibility properties. Only the\nwhole combination should be unique, and nothing here enforces even that.\n\n**`type: \"09\"` — accessibility.** `value` must be a code from\n[Codelist 196](https://ns.editeur.org/onix/en/196); anything else is rejected with\n`400 Bad Request`. An e-book declares its accessibility by carrying *one record per\nproperty*, not one record with a list. The codes fall into four uses.\n\nBlanket statements:\n\n- `08` — unknown accessibility\n- `09` — inaccessible, or known limited accessibility\n\n`08` is a common seeded default on a new e-book, and it means \"not yet assessed\", not\n\"accessible\". Nothing prevents `08` from coexisting with a detailed declaration; where\nboth are present, the detailed codes are the more specific statement.\n\nConformance claims:\n\n- `01` — LIA compliance scheme\n- `02` — EPUB Accessibility Specification 1.0 A\n- `03` — EPUB Accessibility Specification 1.0 AA\n- `04` — EPUB Accessibility Specification 1.1\n- `05` — PDF/UA-1\n- `06` — PDF/UA-2\n- `80`, `81`, `82` — WCAG 2.0, 2.1, 2.2\n- `84`, `85`, `86` — WCAG level A, AA, AAA\n\nIndividual accessibility properties, the substance of a European Accessibility Act\ndeclaration:\n\n- `10` — no reading-system accessibility options actively disabled\n- `11` — table of contents navigation\n- `12` — index navigation\n- `13` — single logical reading order\n- `14` — short alternative textual descriptions\n- `15` — full alternative textual descriptions\n- `19` — print-equivalent page numbering\n- `20` — synchronised pre-recorded audio\n- `21` — text-to-speech hinting provided\n- `22` — language tagging provided\n- `24` — dyslexia readability\n- `25` — use of colour is not the sole means of conveying information\n- `26` — high contrast between text and background\n- `29` — next / previous structural navigation\n- `30` — ARIA roles provided\n- `32` — landmark navigation\n- `36` — appearance of all textual content can be modified\n- `37` — ultra-high contrast between text and background\n- `41` — page-list navigation\n- `52` — all non-decorative content supports reading without sight\n\nExceptions and contact points:\n\n- `75`, `76`, `77` — EAA exceptions: micro-enterprise, disproportionate burden,\n  fundamental alteration\n- `94` — compliance web page for detailed accessibility information\n- `96` — publisher's web page for detailed accessibility information\n- `99` — publisher contact for further accessibility information\n- `00` — accessibility summary\n\nThe last two put their real payload in `description` rather than in `value`; see\n`description`.\n\n**`type: \"12\"` — hazard warnings.** `value` must be a code from\n[Codelist 143](https://ns.editeur.org/onix/en/143), otherwise `400 Bad Request`. `00`\nmeans *no known hazards or warnings* — an explicit \"this was checked and there is\nnothing\", which is not the same as omitting the feature. The remaining 23 codes are the\nCPSIA choking, strangulation, magnet, flashing, sound and motion-simulation warnings,\ntheir \"no warning necessary\" counterparts, and the California Proposition 65 warnings.\n\n**`type: \"15\"` — e-publication format version.** ONIX expects a\n[Codelist 220](https://ns.editeur.org/onix/en/220) version code here:\n\n- `101A`–`101F` — EPUB 2.0.1, 3.0, 3.0.1, 3.1, 3.2, 3.3\n- `107C`, `107D`, `107G`, `107J` — PDF 1.3, 1.4, 1.7, 2.0\n- `116A`, `116B`, `116C` — Kindle MOBI 7, KF8, KFX\n\n**This endpoint does not validate `value` for `type` `15`**: any value at all is\naccepted, including one that is not a Codelist 220 code. A `15` feature also has to name\nthe specific e-book file format it applies to (EPUB, PDF, Mobipocket, iBooks), and that\ncannot be supplied through this endpoint, so a `15` feature created here is incomplete.\n\n**Every other `type`.** No validation, and the value is whatever the ONIX definition of\nthat type calls for — a colour name for `01`/`02`/`26`, a percentage for `36`/`37`, a\nURL for `43`, or an empty string where the presence of the code is itself the whole\nstatement. A very long value is silently truncated rather than rejected.\n\nNot filterable: only `type` and `product_type` are.\n",
            "example": "10"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free-text qualifier for the cases where the code in `value` is not enough on its own.\n`null` whenever it is unset, which is the usual state.\n\nIt carries the substance of the record for exactly two accessibility codes:\n\n- **`type: \"09\"`, `value: \"00\"`** (accessibility summary) — `value` is only a marker;\n  the prose summary itself, or a URL pointing to one, lives here. A new title can be\n  seeded with a house default from the realm's configuration.\n- **`type: \"09\"`, `value: \"99\"`** (publisher contact for further accessibility\n  information) — the contact address belongs here. Nothing on the write path requires\n  it: a `99` record with an empty `description` is accepted as readily as a complete\n  one.\n\nAn explicit `null` clears the field; omitting the key on a `PUT` leaves it unchanged. A\nvery long value is silently truncated rather than rejected.\n",
            "example": null
        }
    },
    "required": [
        "type",
        "value",
        "product_type"
    ]
}

{
    "errors": [
        {
            "_id": "string",
            "stack_trace": [
                "string"
            ],
            "message": "string",
            "vars": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "errors"
    ],
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of errors occurred",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "_id",
                    "message",
                    "stack_trace",
                    "vars"
                ],
                "properties": {
                    "_id": {
                        "type": "string",
                        "description": "The identifier of the error"
                    },
                    "stack_trace": {
                        "type": "array",
                        "description": "A stacktrace of the error occurred. Only for testing systems.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "message": {
                        "type": "string",
                        "description": "A translated message of the error"
                    },
                    "vars": {
                        "type": "object",
                        "description": "A dict containing additional values of the context of the error."
                    }
                }
            }
        }
    }
}

GET /resource/v4/products/{product_id}/form_features/{feature_id}

Get a Product Form Feature

Description

Returns one feature, addressed by the integer _id from the list response.

The feature must belong to the product named in the path. A request for a feature that exists but belongs to a different product returns 403 Permission denied, not 404 — the parent check happens before the record is disclosed. A feature_id that exists nowhere returns 404 Resource not found.

Input parameters

Path parameters

Parameter Type Default Nullable Description
feature_id string No The feature's `_id` — a legacy integer such as `1142596`. The record's UUID also resolves here even though the API never returns it, so the integer is the only identifier an integration can rely on.
product_id string No UUID of the product.

Responses

{
    "_id": 1142596,
    "description": null,
    "product_type": "ebook",
    "type": "09",
    "value": "10"
}
Schema of the response body
{
    "type": "object",
    "description": "One characteristic of one of a product's formats, as an ONIX 3 ProductFormFeature composite.",
    "properties": {
        "_id": {
            "type": "string",
            "description": "Identifier of the feature record, and the value to use as the `{feature_id}` path\nsegment.\n\n**This is a legacy integer, not a UUID.** Although the schema declares `string`, the\nvalue arrives as a JSON number such as `1142596` — unquoted — and a client must be\nprepared to read it as a number. The v4 response for this sub-resource is\nbyte-identical to the v3 one: unlike prices, titles or files, form features carry no\n`_legacy_id`, no `_version` and no per-item `_links`. A UUID does also resolve as the\n`{feature_id}` path segment, but the API never returns one, so this integer is the only\nidentifier an integration can obtain and use.\n\nThe list response likewise arrives as the paginated\n`{_links, _pagination, items}` envelope rather than as the bare array the `200` schema\ndeclares.\n",
            "example": 1142596
        },
        "product_type": {
            "type": "string",
            "description": "Which of the product's formats this feature describes. A single product carries\nall of its editions at once — the printed book, the e-book, the audiobook — so a\nfeature that is true of the e-book is not automatically true of the hardback, and every\nrecord names its format explicitly. Filtering by `product_type` selects what is true of\none edition.\n\nFour formats are accepted:\n\n- `ebook` — the e-book edition (EPUB, PDF, Kindle). Carries the accessibility (`09`),\n  hazard-warning (`12`) and format-version (`15`) features.\n- `book` — the printed edition. Carries the physical features — binding and page-edge\n  colours and paper certification.\n- `audiobook` — the audiobook edition.\n- `nonbook` — a non-book product such as a game or merchandise.\n\nThree legacy aliases also resolve to `ebook`:\n\n- `epub`\n- `mobi`\n- `ibooks`\n\nThe value is matched case-insensitively on write and always returned lowercase, so\n`EBOOK`, `Ebook` and `ebook` are one value. Anything else — including the platform's\nnon-publication product types such as `service`, `fee` or `shipment` — is rejected with\n`400 Bad Request`.\n\nFilterable — `?product_type=ebook`. See [Resource Queries](/resource_queries/).\n",
            "example": "ebook",
            "x-enum-descriptions": {
                "ebook": "E-book edition (EPUB, PDF, Kindle). Carries accessibility (`type` `09`), hazard warnings (`12`) and format-version (`15`) features.",
                "book": "Printed edition. Carries the physical features — binding and page-edge colours and paper certification.",
                "audiobook": "Audiobook edition.",
                "nonbook": "Non-book product such as a game or merchandise."
            }
        },
        "type": {
            "type": "string",
            "description": "The characteristic being described: a code from\n[Codelist 79](https://ns.editeur.org/onix/en/79). All 59 codes of the ONIX 3.1\nrevision of that list are accepted — the list is not contiguous, and `11`, `28` and\n`29` are not among them — and an unrecognised code is rejected with `400 Bad Request`.\n\n`type` is half of a pair: it decides which vocabulary `value` must come from. There is\nno single list of legal values, and only two pairings are checked on write; see `value`.\n\nThe list groups into families. Broadly:\n\n- **Physical make-up of a printed book** — `01` colour of cover, `26` colour of spine,\n  `02` colour of page edges, `55` endpapers, `57` ribbon marker(s), `58` head and tail\n  bands, `27`/`59` foil on cover/jacket, `03` text font, `04` special cover material.\n- **Digital publications** — `09` e-publication accessibility detail, `10`/`15`/`16`\n  e-publication format version (free text / coded / validator version), `18`\n  authentication and access control, `06`/`07` operating-system and other system\n  requirements.\n- **Product safety** — `12` US CPSIA or other international hazard warning, `13` EU\n  General Product Safety Regulation / Toy Safety Directive warning, `14` IATA dangerous\n  goods, `19`–`21` batteries and dangerous goods, `25` personal data requirements.\n- **Paper and carbon certification** — `30`–`40` FSC / PEFC / recycled content / \"green\"\n  inks and adhesives, `41`–`46` carbon and greenhouse-gas certification.\n- **Raw-material sourcing** — `47`–`54`, `56` and `60`–`62`. Accepted values whose\n  meanings are defined by Codelist 79; nothing here interprets them.\n\n**Three of these types are treated specially**; for the rest `value` is returned exactly\nas it was supplied and is not interpreted:\n\n- `09` **E-publication accessibility detail** — `value` is validated against\n  [Codelist 196](https://ns.editeur.org/onix/en/196).\n- `12` **US CPSIA or other international hazard warning** — `value` is validated\n  against [Codelist 143](https://ns.editeur.org/onix/en/143).\n- `15` **E-publication format version code** — records which EPUB, PDF or Kindle\n  version a file is, using [Codelist 220](https://ns.editeur.org/onix/en/220).\n  Incomplete when written here; see `value`.\n\nFor every other code, `value` is accepted verbatim with no validation at all — a colour\nname, a percentage, a URL, or a code belonging to a codelist other than the one ONIX\nnominates for that type. Nothing reports such a value as wrong.\n\nAccessibility and hazard-warning features are also seeded from the realm's configured\ndefaults when a product is first initialised, so a product can already carry `09` and\n`12` records that no client created:\n\n- Codelist 196 codes seeded as `09` features on the **e-book only**, together with the\n  text of a `00` summary record where one is configured.\n- Codelist 143 codes seeded as `12` features, separately configurable for the e-book and\n  for the printed book.\n\nSeeding runs when a product is first initialised, which is not the same event as\n`POST /resource/v4/products`: that endpoint creates a product without defaults.\n\nFilterable — `?type=09`, `?type__ne=09`. See\n[Resource Queries](/resource_queries/).\n",
            "example": "09"
        },
        "value": {
            "type": "string",
            "description": "The coded answer to the characteristic in `type`. Its permitted vocabulary is decided by\n`type`, so \"valid\" here is not a fixed list.\n\nThe same `type` may legitimately appear many times on one product with different\nvalues — that is how an e-book declares a list of accessibility properties. Only the\nwhole combination should be unique, and nothing here enforces even that.\n\n**`type: \"09\"` — accessibility.** `value` must be a code from\n[Codelist 196](https://ns.editeur.org/onix/en/196); anything else is rejected with\n`400 Bad Request`. An e-book declares its accessibility by carrying *one record per\nproperty*, not one record with a list. The codes fall into four uses.\n\nBlanket statements:\n\n- `08` — unknown accessibility\n- `09` — inaccessible, or known limited accessibility\n\n`08` is a common seeded default on a new e-book, and it means \"not yet assessed\", not\n\"accessible\". Nothing prevents `08` from coexisting with a detailed declaration; where\nboth are present, the detailed codes are the more specific statement.\n\nConformance claims:\n\n- `01` — LIA compliance scheme\n- `02` — EPUB Accessibility Specification 1.0 A\n- `03` — EPUB Accessibility Specification 1.0 AA\n- `04` — EPUB Accessibility Specification 1.1\n- `05` — PDF/UA-1\n- `06` — PDF/UA-2\n- `80`, `81`, `82` — WCAG 2.0, 2.1, 2.2\n- `84`, `85`, `86` — WCAG level A, AA, AAA\n\nIndividual accessibility properties, the substance of a European Accessibility Act\ndeclaration:\n\n- `10` — no reading-system accessibility options actively disabled\n- `11` — table of contents navigation\n- `12` — index navigation\n- `13` — single logical reading order\n- `14` — short alternative textual descriptions\n- `15` — full alternative textual descriptions\n- `19` — print-equivalent page numbering\n- `20` — synchronised pre-recorded audio\n- `21` — text-to-speech hinting provided\n- `22` — language tagging provided\n- `24` — dyslexia readability\n- `25` — use of colour is not the sole means of conveying information\n- `26` — high contrast between text and background\n- `29` — next / previous structural navigation\n- `30` — ARIA roles provided\n- `32` — landmark navigation\n- `36` — appearance of all textual content can be modified\n- `37` — ultra-high contrast between text and background\n- `41` — page-list navigation\n- `52` — all non-decorative content supports reading without sight\n\nExceptions and contact points:\n\n- `75`, `76`, `77` — EAA exceptions: micro-enterprise, disproportionate burden,\n  fundamental alteration\n- `94` — compliance web page for detailed accessibility information\n- `96` — publisher's web page for detailed accessibility information\n- `99` — publisher contact for further accessibility information\n- `00` — accessibility summary\n\nThe last two put their real payload in `description` rather than in `value`; see\n`description`.\n\n**`type: \"12\"` — hazard warnings.** `value` must be a code from\n[Codelist 143](https://ns.editeur.org/onix/en/143), otherwise `400 Bad Request`. `00`\nmeans *no known hazards or warnings* — an explicit \"this was checked and there is\nnothing\", which is not the same as omitting the feature. The remaining 23 codes are the\nCPSIA choking, strangulation, magnet, flashing, sound and motion-simulation warnings,\ntheir \"no warning necessary\" counterparts, and the California Proposition 65 warnings.\n\n**`type: \"15\"` — e-publication format version.** ONIX expects a\n[Codelist 220](https://ns.editeur.org/onix/en/220) version code here:\n\n- `101A`–`101F` — EPUB 2.0.1, 3.0, 3.0.1, 3.1, 3.2, 3.3\n- `107C`, `107D`, `107G`, `107J` — PDF 1.3, 1.4, 1.7, 2.0\n- `116A`, `116B`, `116C` — Kindle MOBI 7, KF8, KFX\n\n**This endpoint does not validate `value` for `type` `15`**: any value at all is\naccepted, including one that is not a Codelist 220 code. A `15` feature also has to name\nthe specific e-book file format it applies to (EPUB, PDF, Mobipocket, iBooks), and that\ncannot be supplied through this endpoint, so a `15` feature created here is incomplete.\n\n**Every other `type`.** No validation, and the value is whatever the ONIX definition of\nthat type calls for — a colour name for `01`/`02`/`26`, a percentage for `36`/`37`, a\nURL for `43`, or an empty string where the presence of the code is itself the whole\nstatement. A very long value is silently truncated rather than rejected.\n\nNot filterable: only `type` and `product_type` are.\n",
            "example": "10"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free-text qualifier for the cases where the code in `value` is not enough on its own.\n`null` whenever it is unset, which is the usual state.\n\nIt carries the substance of the record for exactly two accessibility codes:\n\n- **`type: \"09\"`, `value: \"00\"`** (accessibility summary) — `value` is only a marker;\n  the prose summary itself, or a URL pointing to one, lives here. A new title can be\n  seeded with a house default from the realm's configuration.\n- **`type: \"09\"`, `value: \"99\"`** (publisher contact for further accessibility\n  information) — the contact address belongs here. Nothing on the write path requires\n  it: a `99` record with an empty `description` is accepted as readily as a complete\n  one.\n\nAn explicit `null` clears the field; omitting the key on a `PUT` leaves it unchanged. A\nvery long value is silently truncated rather than rejected.\n",
            "example": null
        }
    },
    "required": [
        "type",
        "value",
        "product_type"
    ]
}

PUT /resource/v4/products/{product_id}/form_features/{feature_id}

Update a Product Form Feature

Description

Updates one feature. Despite being a PUT this is a partial update: the existing record is loaded first and only the keys present in the body are applied. Any key left out keeps its current value, a body of {} changes nothing, and description cannot be cleared by omission — that takes an explicit null.

The full validation described under POST runs again on the merged record, so changing type from 01 to 09 without also changing value fails if the old value is not a Codelist 196 code.

_id is stable across an update.

The example changes an EPUB Accessibility 1.0 AA claim (03) to a 1.1 claim (04).

Input parameters

Path parameters

Parameter Type Default Nullable Description
feature_id string No The feature's `_id` — a legacy integer such as `1520172`.
product_id string No UUID of the product.

Request body

{
    "value": "04"
}
Schema of the request body
{
    "type": "object",
    "description": "One characteristic of one of a product's formats, as an ONIX 3 ProductFormFeature composite.",
    "properties": {
        "_id": {
            "type": "string",
            "description": "Identifier of the feature record, and the value to use as the `{feature_id}` path\nsegment.\n\n**This is a legacy integer, not a UUID.** Although the schema declares `string`, the\nvalue arrives as a JSON number such as `1142596` — unquoted — and a client must be\nprepared to read it as a number. The v4 response for this sub-resource is\nbyte-identical to the v3 one: unlike prices, titles or files, form features carry no\n`_legacy_id`, no `_version` and no per-item `_links`. A UUID does also resolve as the\n`{feature_id}` path segment, but the API never returns one, so this integer is the only\nidentifier an integration can obtain and use.\n\nThe list response likewise arrives as the paginated\n`{_links, _pagination, items}` envelope rather than as the bare array the `200` schema\ndeclares.\n",
            "example": 1142596
        },
        "product_type": {
            "type": "string",
            "description": "Which of the product's formats this feature describes. A single product carries\nall of its editions at once — the printed book, the e-book, the audiobook — so a\nfeature that is true of the e-book is not automatically true of the hardback, and every\nrecord names its format explicitly. Filtering by `product_type` selects what is true of\none edition.\n\nFour formats are accepted:\n\n- `ebook` — the e-book edition (EPUB, PDF, Kindle). Carries the accessibility (`09`),\n  hazard-warning (`12`) and format-version (`15`) features.\n- `book` — the printed edition. Carries the physical features — binding and page-edge\n  colours and paper certification.\n- `audiobook` — the audiobook edition.\n- `nonbook` — a non-book product such as a game or merchandise.\n\nThree legacy aliases also resolve to `ebook`:\n\n- `epub`\n- `mobi`\n- `ibooks`\n\nThe value is matched case-insensitively on write and always returned lowercase, so\n`EBOOK`, `Ebook` and `ebook` are one value. Anything else — including the platform's\nnon-publication product types such as `service`, `fee` or `shipment` — is rejected with\n`400 Bad Request`.\n\nFilterable — `?product_type=ebook`. See [Resource Queries](/resource_queries/).\n",
            "example": "ebook",
            "x-enum-descriptions": {
                "ebook": "E-book edition (EPUB, PDF, Kindle). Carries accessibility (`type` `09`), hazard warnings (`12`) and format-version (`15`) features.",
                "book": "Printed edition. Carries the physical features — binding and page-edge colours and paper certification.",
                "audiobook": "Audiobook edition.",
                "nonbook": "Non-book product such as a game or merchandise."
            }
        },
        "type": {
            "type": "string",
            "description": "The characteristic being described: a code from\n[Codelist 79](https://ns.editeur.org/onix/en/79). All 59 codes of the ONIX 3.1\nrevision of that list are accepted — the list is not contiguous, and `11`, `28` and\n`29` are not among them — and an unrecognised code is rejected with `400 Bad Request`.\n\n`type` is half of a pair: it decides which vocabulary `value` must come from. There is\nno single list of legal values, and only two pairings are checked on write; see `value`.\n\nThe list groups into families. Broadly:\n\n- **Physical make-up of a printed book** — `01` colour of cover, `26` colour of spine,\n  `02` colour of page edges, `55` endpapers, `57` ribbon marker(s), `58` head and tail\n  bands, `27`/`59` foil on cover/jacket, `03` text font, `04` special cover material.\n- **Digital publications** — `09` e-publication accessibility detail, `10`/`15`/`16`\n  e-publication format version (free text / coded / validator version), `18`\n  authentication and access control, `06`/`07` operating-system and other system\n  requirements.\n- **Product safety** — `12` US CPSIA or other international hazard warning, `13` EU\n  General Product Safety Regulation / Toy Safety Directive warning, `14` IATA dangerous\n  goods, `19`–`21` batteries and dangerous goods, `25` personal data requirements.\n- **Paper and carbon certification** — `30`–`40` FSC / PEFC / recycled content / \"green\"\n  inks and adhesives, `41`–`46` carbon and greenhouse-gas certification.\n- **Raw-material sourcing** — `47`–`54`, `56` and `60`–`62`. Accepted values whose\n  meanings are defined by Codelist 79; nothing here interprets them.\n\n**Three of these types are treated specially**; for the rest `value` is returned exactly\nas it was supplied and is not interpreted:\n\n- `09` **E-publication accessibility detail** — `value` is validated against\n  [Codelist 196](https://ns.editeur.org/onix/en/196).\n- `12` **US CPSIA or other international hazard warning** — `value` is validated\n  against [Codelist 143](https://ns.editeur.org/onix/en/143).\n- `15` **E-publication format version code** — records which EPUB, PDF or Kindle\n  version a file is, using [Codelist 220](https://ns.editeur.org/onix/en/220).\n  Incomplete when written here; see `value`.\n\nFor every other code, `value` is accepted verbatim with no validation at all — a colour\nname, a percentage, a URL, or a code belonging to a codelist other than the one ONIX\nnominates for that type. Nothing reports such a value as wrong.\n\nAccessibility and hazard-warning features are also seeded from the realm's configured\ndefaults when a product is first initialised, so a product can already carry `09` and\n`12` records that no client created:\n\n- Codelist 196 codes seeded as `09` features on the **e-book only**, together with the\n  text of a `00` summary record where one is configured.\n- Codelist 143 codes seeded as `12` features, separately configurable for the e-book and\n  for the printed book.\n\nSeeding runs when a product is first initialised, which is not the same event as\n`POST /resource/v4/products`: that endpoint creates a product without defaults.\n\nFilterable — `?type=09`, `?type__ne=09`. See\n[Resource Queries](/resource_queries/).\n",
            "example": "09"
        },
        "value": {
            "type": "string",
            "description": "The coded answer to the characteristic in `type`. Its permitted vocabulary is decided by\n`type`, so \"valid\" here is not a fixed list.\n\nThe same `type` may legitimately appear many times on one product with different\nvalues — that is how an e-book declares a list of accessibility properties. Only the\nwhole combination should be unique, and nothing here enforces even that.\n\n**`type: \"09\"` — accessibility.** `value` must be a code from\n[Codelist 196](https://ns.editeur.org/onix/en/196); anything else is rejected with\n`400 Bad Request`. An e-book declares its accessibility by carrying *one record per\nproperty*, not one record with a list. The codes fall into four uses.\n\nBlanket statements:\n\n- `08` — unknown accessibility\n- `09` — inaccessible, or known limited accessibility\n\n`08` is a common seeded default on a new e-book, and it means \"not yet assessed\", not\n\"accessible\". Nothing prevents `08` from coexisting with a detailed declaration; where\nboth are present, the detailed codes are the more specific statement.\n\nConformance claims:\n\n- `01` — LIA compliance scheme\n- `02` — EPUB Accessibility Specification 1.0 A\n- `03` — EPUB Accessibility Specification 1.0 AA\n- `04` — EPUB Accessibility Specification 1.1\n- `05` — PDF/UA-1\n- `06` — PDF/UA-2\n- `80`, `81`, `82` — WCAG 2.0, 2.1, 2.2\n- `84`, `85`, `86` — WCAG level A, AA, AAA\n\nIndividual accessibility properties, the substance of a European Accessibility Act\ndeclaration:\n\n- `10` — no reading-system accessibility options actively disabled\n- `11` — table of contents navigation\n- `12` — index navigation\n- `13` — single logical reading order\n- `14` — short alternative textual descriptions\n- `15` — full alternative textual descriptions\n- `19` — print-equivalent page numbering\n- `20` — synchronised pre-recorded audio\n- `21` — text-to-speech hinting provided\n- `22` — language tagging provided\n- `24` — dyslexia readability\n- `25` — use of colour is not the sole means of conveying information\n- `26` — high contrast between text and background\n- `29` — next / previous structural navigation\n- `30` — ARIA roles provided\n- `32` — landmark navigation\n- `36` — appearance of all textual content can be modified\n- `37` — ultra-high contrast between text and background\n- `41` — page-list navigation\n- `52` — all non-decorative content supports reading without sight\n\nExceptions and contact points:\n\n- `75`, `76`, `77` — EAA exceptions: micro-enterprise, disproportionate burden,\n  fundamental alteration\n- `94` — compliance web page for detailed accessibility information\n- `96` — publisher's web page for detailed accessibility information\n- `99` — publisher contact for further accessibility information\n- `00` — accessibility summary\n\nThe last two put their real payload in `description` rather than in `value`; see\n`description`.\n\n**`type: \"12\"` — hazard warnings.** `value` must be a code from\n[Codelist 143](https://ns.editeur.org/onix/en/143), otherwise `400 Bad Request`. `00`\nmeans *no known hazards or warnings* — an explicit \"this was checked and there is\nnothing\", which is not the same as omitting the feature. The remaining 23 codes are the\nCPSIA choking, strangulation, magnet, flashing, sound and motion-simulation warnings,\ntheir \"no warning necessary\" counterparts, and the California Proposition 65 warnings.\n\n**`type: \"15\"` — e-publication format version.** ONIX expects a\n[Codelist 220](https://ns.editeur.org/onix/en/220) version code here:\n\n- `101A`–`101F` — EPUB 2.0.1, 3.0, 3.0.1, 3.1, 3.2, 3.3\n- `107C`, `107D`, `107G`, `107J` — PDF 1.3, 1.4, 1.7, 2.0\n- `116A`, `116B`, `116C` — Kindle MOBI 7, KF8, KFX\n\n**This endpoint does not validate `value` for `type` `15`**: any value at all is\naccepted, including one that is not a Codelist 220 code. A `15` feature also has to name\nthe specific e-book file format it applies to (EPUB, PDF, Mobipocket, iBooks), and that\ncannot be supplied through this endpoint, so a `15` feature created here is incomplete.\n\n**Every other `type`.** No validation, and the value is whatever the ONIX definition of\nthat type calls for — a colour name for `01`/`02`/`26`, a percentage for `36`/`37`, a\nURL for `43`, or an empty string where the presence of the code is itself the whole\nstatement. A very long value is silently truncated rather than rejected.\n\nNot filterable: only `type` and `product_type` are.\n",
            "example": "10"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free-text qualifier for the cases where the code in `value` is not enough on its own.\n`null` whenever it is unset, which is the usual state.\n\nIt carries the substance of the record for exactly two accessibility codes:\n\n- **`type: \"09\"`, `value: \"00\"`** (accessibility summary) — `value` is only a marker;\n  the prose summary itself, or a URL pointing to one, lives here. A new title can be\n  seeded with a house default from the realm's configuration.\n- **`type: \"09\"`, `value: \"99\"`** (publisher contact for further accessibility\n  information) — the contact address belongs here. Nothing on the write path requires\n  it: a `99` record with an empty `description` is accepted as readily as a complete\n  one.\n\nAn explicit `null` clears the field; omitting the key on a `PUT` leaves it unchanged. A\nvery long value is silently truncated rather than rejected.\n",
            "example": null
        }
    },
    "required": [
        "type",
        "value",
        "product_type"
    ]
}

Responses

{
    "_id": 1520172,
    "description": null,
    "product_type": "ebook",
    "type": "09",
    "value": "04"
}
Schema of the response body
{
    "type": "object",
    "description": "One characteristic of one of a product's formats, as an ONIX 3 ProductFormFeature composite.",
    "properties": {
        "_id": {
            "type": "string",
            "description": "Identifier of the feature record, and the value to use as the `{feature_id}` path\nsegment.\n\n**This is a legacy integer, not a UUID.** Although the schema declares `string`, the\nvalue arrives as a JSON number such as `1142596` — unquoted — and a client must be\nprepared to read it as a number. The v4 response for this sub-resource is\nbyte-identical to the v3 one: unlike prices, titles or files, form features carry no\n`_legacy_id`, no `_version` and no per-item `_links`. A UUID does also resolve as the\n`{feature_id}` path segment, but the API never returns one, so this integer is the only\nidentifier an integration can obtain and use.\n\nThe list response likewise arrives as the paginated\n`{_links, _pagination, items}` envelope rather than as the bare array the `200` schema\ndeclares.\n",
            "example": 1142596
        },
        "product_type": {
            "type": "string",
            "description": "Which of the product's formats this feature describes. A single product carries\nall of its editions at once — the printed book, the e-book, the audiobook — so a\nfeature that is true of the e-book is not automatically true of the hardback, and every\nrecord names its format explicitly. Filtering by `product_type` selects what is true of\none edition.\n\nFour formats are accepted:\n\n- `ebook` — the e-book edition (EPUB, PDF, Kindle). Carries the accessibility (`09`),\n  hazard-warning (`12`) and format-version (`15`) features.\n- `book` — the printed edition. Carries the physical features — binding and page-edge\n  colours and paper certification.\n- `audiobook` — the audiobook edition.\n- `nonbook` — a non-book product such as a game or merchandise.\n\nThree legacy aliases also resolve to `ebook`:\n\n- `epub`\n- `mobi`\n- `ibooks`\n\nThe value is matched case-insensitively on write and always returned lowercase, so\n`EBOOK`, `Ebook` and `ebook` are one value. Anything else — including the platform's\nnon-publication product types such as `service`, `fee` or `shipment` — is rejected with\n`400 Bad Request`.\n\nFilterable — `?product_type=ebook`. See [Resource Queries](/resource_queries/).\n",
            "example": "ebook",
            "x-enum-descriptions": {
                "ebook": "E-book edition (EPUB, PDF, Kindle). Carries accessibility (`type` `09`), hazard warnings (`12`) and format-version (`15`) features.",
                "book": "Printed edition. Carries the physical features — binding and page-edge colours and paper certification.",
                "audiobook": "Audiobook edition.",
                "nonbook": "Non-book product such as a game or merchandise."
            }
        },
        "type": {
            "type": "string",
            "description": "The characteristic being described: a code from\n[Codelist 79](https://ns.editeur.org/onix/en/79). All 59 codes of the ONIX 3.1\nrevision of that list are accepted — the list is not contiguous, and `11`, `28` and\n`29` are not among them — and an unrecognised code is rejected with `400 Bad Request`.\n\n`type` is half of a pair: it decides which vocabulary `value` must come from. There is\nno single list of legal values, and only two pairings are checked on write; see `value`.\n\nThe list groups into families. Broadly:\n\n- **Physical make-up of a printed book** — `01` colour of cover, `26` colour of spine,\n  `02` colour of page edges, `55` endpapers, `57` ribbon marker(s), `58` head and tail\n  bands, `27`/`59` foil on cover/jacket, `03` text font, `04` special cover material.\n- **Digital publications** — `09` e-publication accessibility detail, `10`/`15`/`16`\n  e-publication format version (free text / coded / validator version), `18`\n  authentication and access control, `06`/`07` operating-system and other system\n  requirements.\n- **Product safety** — `12` US CPSIA or other international hazard warning, `13` EU\n  General Product Safety Regulation / Toy Safety Directive warning, `14` IATA dangerous\n  goods, `19`–`21` batteries and dangerous goods, `25` personal data requirements.\n- **Paper and carbon certification** — `30`–`40` FSC / PEFC / recycled content / \"green\"\n  inks and adhesives, `41`–`46` carbon and greenhouse-gas certification.\n- **Raw-material sourcing** — `47`–`54`, `56` and `60`–`62`. Accepted values whose\n  meanings are defined by Codelist 79; nothing here interprets them.\n\n**Three of these types are treated specially**; for the rest `value` is returned exactly\nas it was supplied and is not interpreted:\n\n- `09` **E-publication accessibility detail** — `value` is validated against\n  [Codelist 196](https://ns.editeur.org/onix/en/196).\n- `12` **US CPSIA or other international hazard warning** — `value` is validated\n  against [Codelist 143](https://ns.editeur.org/onix/en/143).\n- `15` **E-publication format version code** — records which EPUB, PDF or Kindle\n  version a file is, using [Codelist 220](https://ns.editeur.org/onix/en/220).\n  Incomplete when written here; see `value`.\n\nFor every other code, `value` is accepted verbatim with no validation at all — a colour\nname, a percentage, a URL, or a code belonging to a codelist other than the one ONIX\nnominates for that type. Nothing reports such a value as wrong.\n\nAccessibility and hazard-warning features are also seeded from the realm's configured\ndefaults when a product is first initialised, so a product can already carry `09` and\n`12` records that no client created:\n\n- Codelist 196 codes seeded as `09` features on the **e-book only**, together with the\n  text of a `00` summary record where one is configured.\n- Codelist 143 codes seeded as `12` features, separately configurable for the e-book and\n  for the printed book.\n\nSeeding runs when a product is first initialised, which is not the same event as\n`POST /resource/v4/products`: that endpoint creates a product without defaults.\n\nFilterable — `?type=09`, `?type__ne=09`. See\n[Resource Queries](/resource_queries/).\n",
            "example": "09"
        },
        "value": {
            "type": "string",
            "description": "The coded answer to the characteristic in `type`. Its permitted vocabulary is decided by\n`type`, so \"valid\" here is not a fixed list.\n\nThe same `type` may legitimately appear many times on one product with different\nvalues — that is how an e-book declares a list of accessibility properties. Only the\nwhole combination should be unique, and nothing here enforces even that.\n\n**`type: \"09\"` — accessibility.** `value` must be a code from\n[Codelist 196](https://ns.editeur.org/onix/en/196); anything else is rejected with\n`400 Bad Request`. An e-book declares its accessibility by carrying *one record per\nproperty*, not one record with a list. The codes fall into four uses.\n\nBlanket statements:\n\n- `08` — unknown accessibility\n- `09` — inaccessible, or known limited accessibility\n\n`08` is a common seeded default on a new e-book, and it means \"not yet assessed\", not\n\"accessible\". Nothing prevents `08` from coexisting with a detailed declaration; where\nboth are present, the detailed codes are the more specific statement.\n\nConformance claims:\n\n- `01` — LIA compliance scheme\n- `02` — EPUB Accessibility Specification 1.0 A\n- `03` — EPUB Accessibility Specification 1.0 AA\n- `04` — EPUB Accessibility Specification 1.1\n- `05` — PDF/UA-1\n- `06` — PDF/UA-2\n- `80`, `81`, `82` — WCAG 2.0, 2.1, 2.2\n- `84`, `85`, `86` — WCAG level A, AA, AAA\n\nIndividual accessibility properties, the substance of a European Accessibility Act\ndeclaration:\n\n- `10` — no reading-system accessibility options actively disabled\n- `11` — table of contents navigation\n- `12` — index navigation\n- `13` — single logical reading order\n- `14` — short alternative textual descriptions\n- `15` — full alternative textual descriptions\n- `19` — print-equivalent page numbering\n- `20` — synchronised pre-recorded audio\n- `21` — text-to-speech hinting provided\n- `22` — language tagging provided\n- `24` — dyslexia readability\n- `25` — use of colour is not the sole means of conveying information\n- `26` — high contrast between text and background\n- `29` — next / previous structural navigation\n- `30` — ARIA roles provided\n- `32` — landmark navigation\n- `36` — appearance of all textual content can be modified\n- `37` — ultra-high contrast between text and background\n- `41` — page-list navigation\n- `52` — all non-decorative content supports reading without sight\n\nExceptions and contact points:\n\n- `75`, `76`, `77` — EAA exceptions: micro-enterprise, disproportionate burden,\n  fundamental alteration\n- `94` — compliance web page for detailed accessibility information\n- `96` — publisher's web page for detailed accessibility information\n- `99` — publisher contact for further accessibility information\n- `00` — accessibility summary\n\nThe last two put their real payload in `description` rather than in `value`; see\n`description`.\n\n**`type: \"12\"` — hazard warnings.** `value` must be a code from\n[Codelist 143](https://ns.editeur.org/onix/en/143), otherwise `400 Bad Request`. `00`\nmeans *no known hazards or warnings* — an explicit \"this was checked and there is\nnothing\", which is not the same as omitting the feature. The remaining 23 codes are the\nCPSIA choking, strangulation, magnet, flashing, sound and motion-simulation warnings,\ntheir \"no warning necessary\" counterparts, and the California Proposition 65 warnings.\n\n**`type: \"15\"` — e-publication format version.** ONIX expects a\n[Codelist 220](https://ns.editeur.org/onix/en/220) version code here:\n\n- `101A`–`101F` — EPUB 2.0.1, 3.0, 3.0.1, 3.1, 3.2, 3.3\n- `107C`, `107D`, `107G`, `107J` — PDF 1.3, 1.4, 1.7, 2.0\n- `116A`, `116B`, `116C` — Kindle MOBI 7, KF8, KFX\n\n**This endpoint does not validate `value` for `type` `15`**: any value at all is\naccepted, including one that is not a Codelist 220 code. A `15` feature also has to name\nthe specific e-book file format it applies to (EPUB, PDF, Mobipocket, iBooks), and that\ncannot be supplied through this endpoint, so a `15` feature created here is incomplete.\n\n**Every other `type`.** No validation, and the value is whatever the ONIX definition of\nthat type calls for — a colour name for `01`/`02`/`26`, a percentage for `36`/`37`, a\nURL for `43`, or an empty string where the presence of the code is itself the whole\nstatement. A very long value is silently truncated rather than rejected.\n\nNot filterable: only `type` and `product_type` are.\n",
            "example": "10"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free-text qualifier for the cases where the code in `value` is not enough on its own.\n`null` whenever it is unset, which is the usual state.\n\nIt carries the substance of the record for exactly two accessibility codes:\n\n- **`type: \"09\"`, `value: \"00\"`** (accessibility summary) — `value` is only a marker;\n  the prose summary itself, or a URL pointing to one, lives here. A new title can be\n  seeded with a house default from the realm's configuration.\n- **`type: \"09\"`, `value: \"99\"`** (publisher contact for further accessibility\n  information) — the contact address belongs here. Nothing on the write path requires\n  it: a `99` record with an empty `description` is accepted as readily as a complete\n  one.\n\nAn explicit `null` clears the field; omitting the key on a `PUT` leaves it unchanged. A\nvery long value is silently truncated rather than rejected.\n",
            "example": null
        }
    },
    "required": [
        "type",
        "value",
        "product_type"
    ]
}

{
    "errors": [
        {
            "_id": "string",
            "stack_trace": [
                "string"
            ],
            "message": "string",
            "vars": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "errors"
    ],
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of errors occurred",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "_id",
                    "message",
                    "stack_trace",
                    "vars"
                ],
                "properties": {
                    "_id": {
                        "type": "string",
                        "description": "The identifier of the error"
                    },
                    "stack_trace": {
                        "type": "array",
                        "description": "A stacktrace of the error occurred. Only for testing systems.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "message": {
                        "type": "string",
                        "description": "A translated message of the error"
                    },
                    "vars": {
                        "type": "object",
                        "description": "A dict containing additional values of the context of the error."
                    }
                }
            }
        }
    }
}

DELETE /resource/v4/products/{product_id}/form_features/{feature_id}

Delete a Product Form Feature

Description

Removes one feature. This is how a claim is withdrawn from an accessibility declaration: there is no "disable" flag.

Deleting the last 09 feature of an e-book does not restore the default that was seeded when the product was initialised. The product is simply left with no accessibility declaration at all.

Input parameters

Path parameters

Parameter Type Default Nullable Description
feature_id string No The feature's `_id` — a legacy integer such as `1520177`.
product_id string No UUID of the product.

Responses


Schemas

Product Form Feature

Name Type Description Example
_id string

Identifier of the feature record, and the value to use as the {feature_id} path segment.

This is a legacy integer, not a UUID. Although the schema declares string, the value arrives as a JSON number such as 1142596 — unquoted — and a client must be prepared to read it as a number. The v4 response for this sub-resource is byte-identical to the v3 one: unlike prices, titles or files, form features carry no _legacy_id, no _version and no per-item _links. A UUID does also resolve as the {feature_id} path segment, but the API never returns one, so this integer is the only identifier an integration can obtain and use.

The list response likewise arrives as the paginated {_links, _pagination, items} envelope rather than as the bare array the 200 schema declares.

1142596
description string| null

Free-text qualifier for the cases where the code in value is not enough on its own. null whenever it is unset, which is the usual state.

It carries the substance of the record for exactly two accessibility codes:

  • type: "09", value: "00" (accessibility summary) — value is only a marker; the prose summary itself, or a URL pointing to one, lives here. A new title can be seeded with a house default from the realm's configuration.
  • type: "09", value: "99" (publisher contact for further accessibility information) — the contact address belongs here. Nothing on the write path requires it: a 99 record with an empty description is accepted as readily as a complete one.

An explicit null clears the field; omitting the key on a PUT leaves it unchanged. A very long value is silently truncated rather than rejected.

product_type string

Which of the product's formats this feature describes. A single product carries all of its editions at once — the printed book, the e-book, the audiobook — so a feature that is true of the e-book is not automatically true of the hardback, and every record names its format explicitly. Filtering by product_type selects what is true of one edition.

Four formats are accepted:

  • ebook — the e-book edition (EPUB, PDF, Kindle). Carries the accessibility (09), hazard-warning (12) and format-version (15) features.
  • book — the printed edition. Carries the physical features — binding and page-edge colours and paper certification.
  • audiobook — the audiobook edition.
  • nonbook — a non-book product such as a game or merchandise.

Three legacy aliases also resolve to ebook:

  • epub
  • mobi
  • ibooks

The value is matched case-insensitively on write and always returned lowercase, so EBOOK, Ebook and ebook are one value. Anything else — including the platform's non-publication product types such as service, fee or shipment — is rejected with 400 Bad Request.

Filterable — ?product_type=ebook. See Resource Queries.

ebook
type string

The characteristic being described: a code from Codelist 79. All 59 codes of the ONIX 3.1 revision of that list are accepted — the list is not contiguous, and 11, 28 and 29 are not among them — and an unrecognised code is rejected with 400 Bad Request.

type is half of a pair: it decides which vocabulary value must come from. There is no single list of legal values, and only two pairings are checked on write; see value.

The list groups into families. Broadly:

  • Physical make-up of a printed book01 colour of cover, 26 colour of spine, 02 colour of page edges, 55 endpapers, 57 ribbon marker(s), 58 head and tail bands, 27/59 foil on cover/jacket, 03 text font, 04 special cover material.
  • Digital publications09 e-publication accessibility detail, 10/15/16 e-publication format version (free text / coded / validator version), 18 authentication and access control, 06/07 operating-system and other system requirements.
  • Product safety12 US CPSIA or other international hazard warning, 13 EU General Product Safety Regulation / Toy Safety Directive warning, 14 IATA dangerous goods, 1921 batteries and dangerous goods, 25 personal data requirements.
  • Paper and carbon certification3040 FSC / PEFC / recycled content / "green" inks and adhesives, 4146 carbon and greenhouse-gas certification.
  • Raw-material sourcing4754, 56 and 6062. Accepted values whose meanings are defined by Codelist 79; nothing here interprets them.

Three of these types are treated specially; for the rest value is returned exactly as it was supplied and is not interpreted:

  • 09 E-publication accessibility detailvalue is validated against Codelist 196.
  • 12 US CPSIA or other international hazard warningvalue is validated against Codelist 143.
  • 15 E-publication format version code — records which EPUB, PDF or Kindle version a file is, using Codelist 220. Incomplete when written here; see value.

For every other code, value is accepted verbatim with no validation at all — a colour name, a percentage, a URL, or a code belonging to a codelist other than the one ONIX nominates for that type. Nothing reports such a value as wrong.

Accessibility and hazard-warning features are also seeded from the realm's configured defaults when a product is first initialised, so a product can already carry 09 and 12 records that no client created:

  • Codelist 196 codes seeded as 09 features on the e-book only, together with the text of a 00 summary record where one is configured.
  • Codelist 143 codes seeded as 12 features, separately configurable for the e-book and for the printed book.

Seeding runs when a product is first initialised, which is not the same event as POST /resource/v4/products: that endpoint creates a product without defaults.

Filterable — ?type=09, ?type__ne=09. See Resource Queries.

09
value string

The coded answer to the characteristic in type. Its permitted vocabulary is decided by type, so "valid" here is not a fixed list.

The same type may legitimately appear many times on one product with different values — that is how an e-book declares a list of accessibility properties. Only the whole combination should be unique, and nothing here enforces even that.

type: "09" — accessibility. value must be a code from Codelist 196; anything else is rejected with 400 Bad Request. An e-book declares its accessibility by carrying one record per property, not one record with a list. The codes fall into four uses.

Blanket statements:

  • 08 — unknown accessibility
  • 09 — inaccessible, or known limited accessibility

08 is a common seeded default on a new e-book, and it means "not yet assessed", not "accessible". Nothing prevents 08 from coexisting with a detailed declaration; where both are present, the detailed codes are the more specific statement.

Conformance claims:

  • 01 — LIA compliance scheme
  • 02 — EPUB Accessibility Specification 1.0 A
  • 03 — EPUB Accessibility Specification 1.0 AA
  • 04 — EPUB Accessibility Specification 1.1
  • 05 — PDF/UA-1
  • 06 — PDF/UA-2
  • 80, 81, 82 — WCAG 2.0, 2.1, 2.2
  • 84, 85, 86 — WCAG level A, AA, AAA

Individual accessibility properties, the substance of a European Accessibility Act declaration:

  • 10 — no reading-system accessibility options actively disabled
  • 11 — table of contents navigation
  • 12 — index navigation
  • 13 — single logical reading order
  • 14 — short alternative textual descriptions
  • 15 — full alternative textual descriptions
  • 19 — print-equivalent page numbering
  • 20 — synchronised pre-recorded audio
  • 21 — text-to-speech hinting provided
  • 22 — language tagging provided
  • 24 — dyslexia readability
  • 25 — use of colour is not the sole means of conveying information
  • 26 — high contrast between text and background
  • 29 — next / previous structural navigation
  • 30 — ARIA roles provided
  • 32 — landmark navigation
  • 36 — appearance of all textual content can be modified
  • 37 — ultra-high contrast between text and background
  • 41 — page-list navigation
  • 52 — all non-decorative content supports reading without sight

Exceptions and contact points:

  • 75, 76, 77 — EAA exceptions: micro-enterprise, disproportionate burden, fundamental alteration
  • 94 — compliance web page for detailed accessibility information
  • 96 — publisher's web page for detailed accessibility information
  • 99 — publisher contact for further accessibility information
  • 00 — accessibility summary

The last two put their real payload in description rather than in value; see description.

type: "12" — hazard warnings. value must be a code from Codelist 143, otherwise 400 Bad Request. 00 means no known hazards or warnings — an explicit "this was checked and there is nothing", which is not the same as omitting the feature. The remaining 23 codes are the CPSIA choking, strangulation, magnet, flashing, sound and motion-simulation warnings, their "no warning necessary" counterparts, and the California Proposition 65 warnings.

type: "15" — e-publication format version. ONIX expects a Codelist 220 version code here:

  • 101A101F — EPUB 2.0.1, 3.0, 3.0.1, 3.1, 3.2, 3.3
  • 107C, 107D, 107G, 107J — PDF 1.3, 1.4, 1.7, 2.0
  • 116A, 116B, 116C — Kindle MOBI 7, KF8, KFX

This endpoint does not validate value for type 15: any value at all is accepted, including one that is not a Codelist 220 code. A 15 feature also has to name the specific e-book file format it applies to (EPUB, PDF, Mobipocket, iBooks), and that cannot be supplied through this endpoint, so a 15 feature created here is incomplete.

Every other type. No validation, and the value is whatever the ONIX definition of that type calls for — a colour name for 01/02/26, a percentage for 36/37, a URL for 43, or an empty string where the presence of the code is itself the whole statement. A very long value is silently truncated rather than rejected.

Not filterable: only type and product_type are.

10