Add a Model Structure

You can add a new component by providing its model structure using the POST method on the modelstructure-for-component endpoint. You need a token with write privileges, otherwise a 401 or 403 will be sent back.

Component metadata

The model structure is accompanied with component metadata, which is made of the three fields that identify a component: an archive, a section and a hypercube report element.

POST http://host.28.io/v1/_queries/public/api/modelstructure-for-component?token=c3049752-4d35-43da-82a2-f89f1b06f7a4
{
    "Archive" : "my-archive",
    "SectionURI" : "http://www.example.com/my-section",
    "HypercubeName" : "my:Hypercube"
    "ModelStructure" [ ... ]
}

Model Structure

The model structure itself is a tree of report elements. It must fulfill the following constraints:

• Each node in the model structure tree has a Name field that contains the qualified name of a report element. This report element MUST exist within the section to which the component belongs.
• The hierarchy must be consistent with the rules given in the previous section on model structure hierarchies.
• Exactly one node in the model structure must be the hypercube report element identified with the HypercubeName field from the component metadata. No other hypercubes are allowed. An exception is the special builtin xbrl28:ImpliedTable hypercube report element, which stands for the adimensional hypercube, and which must not appear in the model structure if HypercubeName is xbrl28:ImpledTable.

Here is an example of model structure for a component associated with a hypercube report element that is not the implied table:

POST http://host.28.io/v1/_queries/public/api/modelstructure-for-component?token=c3049752-4d35-43da-82a2-f89f1b06f7a4
{
    "Archive" : "my-archive",
    "SectionURI" : "http://www.example.com/my-section",
    "HypercubeName" : "my:Hypercube"
    "ModelStructure": [
      {
        "Name": "foo:Abstract1",
        "Children": [
          {
            "Name": "foo:Hypercube1",
            "Children": [
              {
                "Name": "foo:Dimension1",
                "Children": [
                  {
                    "Name": "foo:Member1"
                  }
                ]
              },
              {
                "Name": "foo:LineItems",
                "Children": [
                  {
                    "Name": "foo:Abstract2",
                    "Children": [
                      {
                        "Name": "foo:Concept1"
                      },
                      {
                        "Name": "foo:Concept2"
                      },
                      {
                        "Name": "foo:Concept3"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
}

And here is an example of model structure for a component that is the implied table of a section. It has no hypercube report element and no dimensional structure, only abstract and concept report elements.

POST http://host.28.io/v1/_queries/public/api/modelstructure-for-component?token=c3049752-4d35-43da-82a2-f89f1b06f7a4
{
    "Archive" : "my-archive",
    "SectionURI" : "http://www.example.com/my-section",
    "HypercubeName" : "xbrl28:ImpliedTable"
    "ModelStructure": [
      {
        "Name": "foo:Abstract1",
        "Children": [
          {
            "Name": "foo:Abstract2",
            "Children": [
              {
                "Name": "foo:Concept1"
              },
              {
                "Name": "foo:Concept2"
              },
              {
                "Name": "foo:Concept3"
              }
            ]
          }
        ]
      }
    ]
}

In general, any object output by a GET on the modelstructure-for-component endpoint will be accepted in a POST, so that you can take a model structure from an archive with a GET and feed them into another archive with a POST.

You can post several component's model structures at a time by sending them concatenated, with no comma separator.

In case of success, an empty response body is issued with a 204 status.

Common HTTP errors

• 400: when the input is invalid or contains duplicate components or inconsistent model structures, or hypercube report elements do not match.
• 401: when the token is missing.
• 403: when you do not have the appropriate write access credentials.
• 404: when the archive or section or report element is not found.
• 409: when the component already exists (same archive, section and hypercube report element).

Further reference

The reference for the REST API including the JSound schema for the input is documented here