Example-5: Validate Inline XBRL
This example uses PowerShell on Windows with the US-GAAP filing from https://www.sec.gov/Archives/edgar/data/815097/000081509723000012/0000815097-23-000012-xbrl.zip to perform an inline XBRL validation.
Prerequisites
•Download 0000815097-23-000012-xbrl.zip (full URL above)
•Install the US-GAAP-2023 taxonomy on the server
| Note: | The use of quotes may be different on other shells ('bash' works with the example when one uses 'curl' instead of 'curl.exe'). |
Submit the Inline-XBRL-validation POST request using CURL
Given below is an example CURL command for submitting an Inline XBRL validation request.
curl.exe -F 'msg={"command": "ixbrl", "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"], "options": {"verbose": true}};type=application/json' -F "additional-files=@0000815097-23-000012-xbrl.zip;type=application/octet-stream" http://localhost:8087/v1/queue
For easier readability:
(1) -F 'msg={
(2) "command": "ixbrl",
(3) "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],
(4) "options": {"verbose": true}
(5) };type=application/json'
(6) -F "additional-files=@0000815097-23-000012-xbrl.zip;type=application/octet-stream"
(7) http://localhost:8087/v1/queue
Input
The different parts of the CURL command are explained below, keyed to the callouts in the listing above.
(1) -F 'msg={...}' specifies a form field with name 'msg'
The -F option: (i) causes CURL to generate a multipart form post with Content-Type: multipart/form-data and (ii) causes this form field to be automatically added to the request header. We use a JSON object to describe the command that RaptorXML+XBRL Server should execute.
Content-Type: multipart/form-data; boundary=--------------------...
CURL translates this option in the HTTP request to:
Content-Disposition: form-data; name="msg"
Content-Type: application/json
{"command": "ixbrl", "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"], "options": {"verbose": true}}
(2) The RaptorXML+XBRL Server command to execute on the server. See the Command Line Interface (CLI) section for information about the commands that can be accepted here. In our example, the command for Inline XBRL validation is valinlinexbrl (ixbrl). Either the long form valinlinexbrl or short form ixbrl is allowed.
(3) The command's arguments (as accepted by the RaptorXML+XBRL Server command line) are encoded as a JSON array. RaptorXML+XBRL Server uses an explicit scheme additional-files:// to reference additional resources inside a separate additional-files form field. In our example, we reference the Inline XBRL document ccl-20221130.htm inside the ZIP file 0000815097-23-000012-xbrl.zip.
| Note: | The | in |zip, which is used in Altova products to reference files inside a .zip archive, has to be URL-encoded as %7C. The 0000815097-23-000012-xbrl.zip file itself is submitted as the content of a different form field in (6). All resources in the args array must be available on the server or submitted with the request, similar to (6). |
(4) The command's options (as accepted by the RaptorXML+XBRL Server command line) are encoded as a JSON object. If the default values of options are as you want them (see the CLI section), then this part can be left out. In our example, we ask for a verbose output log by setting the verbose option to true (the option's default value is false).
(5) The Content-Type of the msg form field is specified after the definition of the form field and is separated from it by a semicolon. In our example, the Content-Type of msg is given by: type=application/json.
(6) Files that contain additional resources for the command can be specified using the additional-files form field. In our example, we specify @0000815097-23-000012-xbrl.zip as the additional resource, followed by a semicolon separator and then its Content-Type, which we give as type=application/octet-stream.
| Note: | Prefix the filename with @ to instruct CURL to (i) use the file name as the value of the filename property and (ii) the content of the file as the form's value. The additional-files form field can be supplied multiple times, once for each additional resource required by the command. CURL translates this option into the following in the HTTP request: |
Content-Disposition: form-data; name="additional-files"; filename="0000815097-23-000012-xbrl.zip"
Content-Type: application/octet-stream
<<content of 0000815097-23-000012-xbrl.zip>>
Output
The RaptorXML+XBRL Server output is a JSON object:
{"jobid": "4B7CFC80-13B3-4558-B8CC-D312EA00BA74", "result": "/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74"}
The JSON object contains a jobid key and a result key. The value of the result key is the path to the result. This path must be appended to the <scheme>://<host>:<port> part used to submit the request. In our example, the full result URL would be: http://localhost:8087/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74. The result URL is also used to ask for the result of the command execution. See Getting the Result Document.
Get error/message/output of the POST request
The input command that is sent to get the error/message/output of the POST request (see Getting Error/Message/Output Documents) would be something like this:
curl.exe http://localhost:8087/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74
In our example, this command returns the following JSON object:
{"jobid":"4B7CFC80-13B3-4558-B8CC-D312EA00BA74","state":"OK","error":{},"jobs":[{"file":["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],"jobid":"94968597-3234-4D0A-A3FF-BCDE50A0E4E6","output":{"verbose-log":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log"],"xbrl-output-file":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl"]},"state":"OK","output-mapping":{"file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log":"verbose.log","file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl":"output.xbrl"},"error":{}}]}
This is transcribed on separate lines below for easier readability and with callouts for easier referencing:
(1) {
(2) "jobid":"4B7CFC80-13B3-4558-B8CC-D312EA00BA74",
(3) "state":"OK",
(4) "error":{},
(5) "jobs":[{
(6) "file":["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],
(7) "jobid":"94968597-3234-4D0A-A3FF-BCDE50A0E4E6",
(8) "output":{
(9) "verbose-log":[file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log"],
(10) "xbrl-output-file":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl"]},
(11) "state":"OK",
(12) "output-mapping":{
(13) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log":"verbose.log",
(14) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl":"output.xbrl"
(15) },
(16) "error":{}
(17) }]
(18) }
Given below is an explanation of this listing:
(1) The result is returned as a JSON object.
(2) The jobid on the first level is the main job identifier.
(3) The state for this job is OK. Possible states are: none; Dispatched; Running; Canceled; Crashed; OK; Failed.
(4) The JSON error object in our example is empty. It may contain the JSON serialization of the error as reported by RaptorXML+XBRL Server.
(5) The main job (on the first level) generates sub-jobs (for example, one per argument).
(6) The argument for the this job is the Inline XBRL instance in the ZIP file: additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm.
(7) Sub-jobs also have a job identifier that can be used to query the state or fetch the results. Job execution is asynchronous. As a result short jobs submitted after longer jobs may finish earlier.
(8) to (15) The JSON output object contains keys for the server-generated output files that can be requested via HTTP. Some keys (such as verbose-log) specify URLs to the generated files stored on the server. These server-local paths can be mapped to names, which can be used as JSON output-mapping objects in HTTP URLs. Such URLs are used to fetch output files via HTTP and are constituted as follows:
<scheme>://<host>:<port>/v1/results/<jobid>/output/<output-mapping-value>
Our example to fetch the verbose log would therefore look like this:
curl.exe http://localhost:8087/v1/results/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output/verbose.log
Note that in the output-mapping object (12), the first value (13), is the verbose-log, file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log and that we have mapped it to the value verbose.log. This enables us to use verbose.log to reference the file.