Declare a role on a standard
const url = 'https://example.com/api/v1/standards/example/roles/example';const options = { method: 'PATCH', headers: {'Content-Type': 'application/json'}, body: '{"accepted_types":["example"],"alternate":"example","capacity":1,"impact":"outage","label":"example","pinned_products":["example"],"position_labels":["example"],"quorum":1,"update_mask":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://example.com/api/v1/standards/example/roles/example \ --header 'Content-Type: application/json' \ --data '{ "accepted_types": [ "example" ], "alternate": "example", "capacity": 1, "impact": "outage", "label": "example", "pinned_products": [ "example" ], "position_labels": [ "example" ], "quorum": 1, "update_mask": [ "example" ] }'Declares a role every conforming system needs filled, or revises it in place (the role is addressed by name, so the write is idempotent and declaring is this same route). Partial by default: the fields present in the body change and the rest of the declaration is left alone. update_mask overrides that, writing exactly the fields it names, which is how a field is cleared, and [”*”] replaces the whole declaration. An unknown standard, type, or product is a 422, as is a mask naming a field this resource does not patch. Gated by standard:update.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The standard id
The standard id
The role name
The role name
Request Body required
Section titled “Request Body required ”object
A URL to the JSON Schema for this object.
The component_types a filling component’s product must be classified within (self or a descendant); replaces the accepted set wholesale when written, and an empty set accepts any type. Clearing it means naming accepted_types in update_mask
The choice/alternate this role joins, addressed as “choice-name/alternate-name” (#626). An empty string detaches the role, making it unconditional; an unknown choice or alternate is a 422
The most components the role will accept; must be at least quorum, and unbounded on first declare. Name capacity in update_mask with no value here to clear it back to unbounded
What an impaired role means for its system; degraded on first declare. The same broken component matters differently depending on the slot it was filling: a dead confidence monitor is not a dead main display
The role’s human label; defaults to the role name on first declare
If set, a filling component’s product must be one of these; replaces the pinned set wholesale when written, and an empty set accepts any product of an accepted type. Clearing it means naming pinned_products in update_mask
Human labels for each position within the role, by index; replaces the label set wholesale when written. An empty list is not a populated field, so clearing the labels means naming position_labels in update_mask
How many components must fill the role; one on first declare
Which fields this write changes (AIP-134). Omit it and the fields present in the body change and nothing else; name a field here and it is written even when the body leaves it empty, which is how a field is CLEARED; send [”*”] for full replacement, where every field the body omits goes back to its default. A field this resource does not patch is a 422 naming it
Responses
Section titled “ Responses ”OK
object
A URL to the JSON Schema for this object.
The component_types a filling component’s product must be classified within (self or a descendant); empty accepts any type
The choice/alternate this role joins, addressed as “choice-name/alternate-name” (#626); absent when the role is unconditional. The same form the write body takes, so a read round-trips into a write
The most components the role will accept; null means no upper bound beyond quorum
What an impaired role means for its system: outage, degraded, or none
The role’s human label
The role’s name within its owner (the address)
If set, a filling component’s product must be one of these; empty accepts any product of an accepted type
Human labels for each position within the role, by index; empty when unlabeled
How many components must fill the role
Example
{ "$schema": "/api/v1/schemas/SystemRoleBody.json"}default
Section titled “default ”Error
object
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
object
Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{ "$schema": "/api/v1/schemas/ErrorModel.json", "detail": "Property foo is required but is missing.", "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "about:blank"}