/api/modelstructure-for-component
GET
Retrieve the model structure for a given component. A component can be selected in several ways, for example with an accession number (AID), section URI and hypercube name, or with a CIK, fiscal year, fiscal period, and disclosure, etc.
Parameters
| Name | Type | Description | Profile |
|---|---|---|---|
| profile-name | query | Specifies which profile to use, which will enable some parameters or modify hypercube queries accordingly. The default depends on the underlying repository | |
| format | query | Returns the results in the supplied format | |
| format-indent | query | Whether or not to indent JSON or XML output (default: no indent). | |
| token | query | The token that allows you to use this API. Gives you read (GET) and/or write (POST, DELETE, PATCH) credentials. | |
| aid | query | Archive IDs, to retrieve archives, sections, components or slice facts. | |
| eid | query | The EIDs (scheme + local name) of a company, to retrieve entities, archives, sections, components or dice facts. | |
| cik | query | The CIK of a company, to retrieve entities, archives, sections, components or dice facts. | sec |
| ticker | query | The ticker of a company, to retrieve entities, archives, sections, components or dice facts. | sec, japan |
| edinetcode | query | The EDINET code of a company, to retrieve entities, archives, sections, components or dice facts. | japan |
| entity-tag | query | The tag of an entity (such as an index), to retrieve entities, archives, sections, components or dice facts. | sec, japan |
| sic | query | The SIC (industry group) of a company, to retrieve entities, archives, sections, components or dice facts. | sec |
| archiveFiscalYear | query | The fiscal year focus of the archive, to retrieve archives, sections, components or slice facts (default: ALL). | sec, japan |
| archiveFiscalPeriod | query | The fiscal period focus of the archive, to retrieve archives, sections, components or slice facts (default: ALL). | sec, japan |
| archive-tag | query | The tag of the archive, to retrieve archives, sections, components or slice facts (default: no filtering). | japan |
| section | query | The URI of a particular section, to retrieve a section, component or report element. | |
| hypercube | query | The name of a hypercube report element, to retrieve components / sections. | |
| disclosure | query | A disclosure, to identify sections or components (e.g. BalanceSheet). | sec, japan |
| reportElement | query | The name of the report element to search for, to retrieve a section, a component or a report element (e.g. us-gaap:Goodwill). | |
| label | query | A search term to search in the labels of components, to retrieve components (e.g. stock). | |
| language | query | A language code (default: en-US) for displaying labels. | |
| indent | query | If set to true all labels will be prepended with 8 space characters for each level of depth within the model structure (default: false). | |
| count | query | If true, only outputs statistics (default: false). | |
| top | query | Output only the first [top] results (default: no limit). | |
| skip | query | Skip the first [skip] results. |
Status codes
| Code | Description |
|---|---|
| 200 | Return the model structure for the given component |
| 401 | Unauthorized: the specified project token is invalid, expired, or has insufficient privileges |
| 404 | No such entity could be found. / No such archive could be found. / No such component could be found |
| 500 | An internal error occurred during the processing of the request |
POST
Add or update components by providing their model structures. The components are identified with an AID, a section URI and the qualified name of a hypercube.
A new component can be created by submitting a JSON object containing the model structure of the component. This JSON object must be valid agains a JSound schema. It can be either taken from the output of a GET request to the same endpoint (in which case it will be valid), or created manually.
For convenience, we offer a user-friendly summary of the fields involved. The JSound schema is available on request.
Body properties
| Field | Type | Presence | Content |
|---|---|---|---|
| AID | string | required | The AID of the archive to which the component belongs |
| SectionURI | string (URI) | optional | The URI of the section to which the component belongs |
| HypercubeName | string (QName lexical space) | required | The name of the hypercube that this component involves |
| ModelStructure | array of model structure node objects | required | The hierarchical model structure, as a tree of nodes that reference report elements (see below) |
Additionally, the following fields are allowed for the purpose of feeding back the output of the modelstructure-for-component endpoint as input:
Model structure node properties
| Field | Type | Presence | Content |
|---|---|---|---|
| Name | string | required | The qualified name of a report element that exists in the component's section |
| Children | array | optional | An array of model structure node objects that reference further children report elements |
Additionally, the following fields are allowed for the purpose of feeding back the output of the modelstructure-for-component endpoint as input:
- Depth (integer)
- Label (string)
- BaseType (string)
- Kind (string)
- Order (integer)
- DataType (string)
- BaseDataType (string)
- Balance (string)
- Abstract (boolean)
- PeriodType (string)
The hierarchy of the model structure must fulfill the constraints described in the documentation of model structures. We repeat it here for convenience:
| Kind of report element | Allowed children |
|---|---|
| Abstract | Hypercube (if top-level), Abstract, Concept |
| Hypercube | Dimension, LineItems |
| Dimension | Member |
| Member | Member |
| LineItems | Abstract, Concept |
| Concept | none |
The model structure MUST involve the hypercube referred to in the top-level HypercubeName field, only this one, and only once, either top-level or below a top-level abstract. Its children are the dimensions with their members, as well as the line items hierarchy.
The only exception to the requirement of the hypercube report element is the special xbrl28:ImpliedTable hypercube. If HypercubeName is xbrl28:ImpliedTable, then the model structure can only involve Abstracts and Concepts, and has no dimensionality.
Several components can be created at the same time by posting a sequence of non-comma-separated JSON model structure objects as above.
Parameters
| Name | Type | Description | Profile |
|---|---|---|---|
| profile-name | query | Specifies which profile to use, which will enable some parameters or modify hypercube queries accordingly. The default depends on the underlying repository | |
| format | query | Returns the results in the supplied format | |
| format-indent | query | Whether or not to indent JSON or XML output (default: no indent). | |
| token | query | The token that allows you to use this API. Gives you read (GET) and/or write (POST, DELETE, PATCH) credentials. | |
| model-structure | body | The model structures, which must satisfy the constraints described in the properties table. |
Status codes
| Code | Description |
|---|---|
| 200 | Components have been added. |
| 400 | One of the supplied model structures is invalid. Or one of the components is a duplicate in the body. Or the supplied HypercubeName is not a hypercube. |
| 401 | Unauthorized: the specified project token is invalid, expired, or has insufficient privileges. |
| 403 | Access denied. |
| 404 | No such archive or section or report element could be found. |
| 409 | The component with the specified archive, section and hypercube already exists. |
| 500 | An internal error occurred during the processing of the request. |
DELETE
Deletes a component including its model structure.
Parameters
| Name | Type | Description | Profile |
|---|---|---|---|
| aid | query | Archive IDs, to retrieve archives, sections, components or slice facts. | |
| section | query | The URI of a particular section, to retrieve a section, component or report element. | |
| hypercube | query | The name of a hypercube report element, to retrieve components / sections. | |
| token | query | The token that allows you to use this API. Gives you read (GET) and/or write (POST, DELETE, PATCH) credentials. |
Status codes
| Code | Description |
|---|---|
| 204 | The report element has been deleted. |
| 400 | Cannot delete more than one component at a time (safety mechanism). |
| 401 | Unauthorized: the specified project token is invalid, expired, or has insufficient privileges. |
| 403 | Access denied. |
| 404 | No such archive or section or component could be found. |
| 500 | An internal error occurred during the processing of the request. |