Exemple-5 : Valider Inline XBRL
Cet exemple utilise PowerShell sur Windows avec US-GAAP filing depuis https://www.sec.gov/Archives/edgar/data/815097/000081509723000012/0000815097-23-000012-xbrl.zip afin de réaliser une validation XBRL inline.
Prérequis
•Téléchargez 0000815097-23-000012-xbrl.zip (URL entière ci-dessus)
•Installez la taxonomie US-GAAP-2023 sur le serveur
| Note : | l’utilisation des guillemets peut être différente sur d’autres shells('bash' fonctionne avec l’exemple quand il utilise 'curl’ à la place de 'curl.exe'). |
Soumettre la requête POST de validation XBRL Inline utilisant CURL
Ci-dessous, vous trouverez un exemple de la commande CURL pour soumettre une requête de validation XBRL Inline.
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
Pour une lisibilité plus facile :
(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
Entrée
La différentes parties de la commande CURL sont expliquées ci-dessous, verrouillées aux callouts dans la liste ci-dessus.
(1) -F 'msg={...}' spécifie un champ de formulaire avec le nom 'msg'
L’option -F fait que : (i) CURL génère un « multipart form post » avec Content-Type: multipart/form-data et (ii) ce champ peut être automatiquement ajouté à l’en-tête de la requête. Nous utilisons un objet JSON pour décrire la commande que RaptorXML+XBRL Server devrait exécuter.
Content-Type: multipart/form-data; boundary=--------------------...
CURL traduit cette option en une requête HTTP en :
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) la commande RaptorXML+XBRL Server à exécuter sur le serveur. Voir la section Command Line Interface (CLI) pour des informations sur les commandes qui peuvent être acceptées ici. Dans notre exemple, la commande pour la validation XBRL Inline est valinlinexbrl (ixbrl). Soit la longue forme valinlinexbrl ou la forme courte ixbrl est autorisée.
(3) Les arguments de la commande (tels qu’acceptés par la ligne de commande RaptorXML+XBRL Server) sont encodés comme array JSON. L’RaptorXML+XBRL Server utilise un schéma explicite additional-files:// pour référencer des ressources supplémentaires à l’intérieur du champ de formulaire additional-files séparé. Dans notre exemple, nous référençons le document XBRL Inline ccl-20221130.htm à l’intérieur du fichier ZIP 0000815097-23-000012-xbrl.zip.
| Note : | Le | dans |zip, qui est utilisé dans les produits Altova pour référencer les fichiers à l’intérieur d’une archive .zip doit être encodé URL comme %7C. Le fichier 0000815097-23-000012-xbrl.zip lui-même est soumis comme contenu d’un champ de formulaire différent dans (6). Toutes les ressources dans l’array args doivent être disponibles sur le serveur ou soumises avec la requête similaire à (6). |
(4) Les options de la commande (tel qu’accepté par la ligne de commande RaptorXML+XBRL Server) sont encodées comme objet JSON. Cette partie est optionnelle au cas où les valeurs par défaut sont adaptées. Dans notre exemple, nous demandons un log de sortie verbose.
(5) Le Content-Type du champ de forme msg est séparé de la valeur du champ de forme par un point-virgule. Dans notre exemple, le Content-Type de msg est donné par : type=application/json.
(6) Les fichiers qui contiennent des ressources supplémentaires pour la commande peuvent être spécifiés utilisant le champ de formulaire additional-files. Dans notre exemple, nous spécifions @0000815097-23-000012-xbrl.zip comme ressource supplémentaire, suivie d’un point-virgule, puis de son Content-Type, que nous donnons comme type=application/octet-stream.
| Note : | Donnez un préfixe au nom de fichier avec @ pour instruire CURL pour (i) utiliser le nom de fichier comme la valeur de la propriété filename et (ii) le contenu du fichier comme la valeur du formulaire. Le champ de formulaire des fichiers supplémentaires peut être fourni de multiples fois, une fois pour chaque ressource supplémentaire requise par la commande. CURL traduit cette option dans la requête HTTP suivante : |
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>>
Sortie
La sortie RaptorXML+XBRL Server est un objet JSON :
{"jobid": "4B7CFC80-13B3-4558-B8CC-D312EA00BA74", "result": "/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74"}
L’objet JSON contient une clé jobid et une clé result. La valeur de la clé result est le chemin au résultat. Ce chemin doit être ajouté à la partie <scheme>://<host>:<port> utilisée pour soumettre la requête. Dans notre exemple, le résultat entier de l’URL serait : http://localhost:8087/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74. Le résultat de l’URL de résultat est aussi utilisé pour demander le résultat de l’exécution de la commande. Voir Obtenir le résultat du document.
Obtenir l’erreur/le message/la sortie de la requête POST
La commande d’entrée qui est envoyée pour recevoir l’erreur/le message/la sortie de la requête POST (voir Obtenir Documents d’erreur/de message/de sortie) serait comme suit :
curl.exe http://localhost:8087/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74
Dans notre exemple, cette commande retourne l’objet JSON suivant :
{"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":{}}]}
Ceci est transcrit ci-dessous pour une lisibilité plus facile et avec des callouts :
(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) }
Ci-dessous, vous trouverez une explication de cette liste :
(1) Le résultat est retourné en tant qu'un objet JSON.
(2) Le jobid au premier niveau est l’identifiant principal de la tâche.
(3) L’état pour cette tâche est OK. Des états possibles sont : none; Dispatched; Running; Canceled; Crashed; OK; Failed.
(4) L’objet d’erreur JSON dans notre exemple est vide. Il peut contenir une sérialisation JSON de l’erreur comme rapporté par RaptorXML+XBRL Server.
(5) La tâche principale (au premier niveau) génère les sous-tâches (par exemple, un par argument).
(6) L’argument pour cette tâche est l’instance XBRL Inline dans le fichier ZIP : additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm.
(7) Les sous-tâches ont également un identifiant de tâche qui peut être utilisé pour interroger l’état de ou chercher les résultats. L’exécution de la tâche est asynchrone. En guise de résultat, des tâches courtes soumises après de longues tâches peuvent être terminées plus tôt.
(8) à (15) L’objet de la sortie JSON contient des clés pour les fichiers de sortie générés par le serveur qui peuvent être demandées via HTTP. Quelques clés (telles que verbose-log) spécifient les URL vers les fichiers générés stockés sur le serveur. Ces chemins « server-local » peuvent être mappés aux noms qui peuvent être utilisés comme faisant partie aux URL HTTP pour les chercher utilisant l’objet JSON output-mapping. LesURL à chercher via HTTP sont assemblés comme suit :
<scheme>://<host>:<port>/v1/results/<jobid>/output/<output-mapping-value>
Notre exemple pour récupérer le log verbose aurait donc l’air de ceci :
curl.exe http://localhost:8087/v1/results/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output/verbose.log
Notez que dans l’objet output-mapping (12) de la liste ci-dessus, la première valeur (13), est le verbose-log, file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log, and that it is mapped to the value verbose.log. Donc nous pouvons utiliser la valeur verbose.log pour mapper vers le fichier.