NLM Style Checker API
The NLM Style Checker API allows programmatic access to the NLM Style Checker.
Base URL: https://www.ncbi.nlm.nih.gov/pmc/utils/style4/v1.0/.
Requests to the service use HTTP POST, with a set of parameters that specify the input data and response format. Responses may be delivered in JSON, XML, or HTML depending on the value set for the parameter -F format
.
Parameters
Note: It is assumed most users will interact with the API via curl, so parameters and examples are expressed in that syntax.
-X POST
- The service accepts only POST requests. (If using -d/--data or -f/--form, -X POST can be omitted, as -d/--data and -f/--form imply POST.)-H "Content-Type: application/json"
- use this if sending data in JSON format-H "Content-Type: text/xml"
- use this if sending data in XML format-H "Accept: application/json"
- to receive response JSON format-H "Accept: text/xml"
- to receive response in XML format-
-d/--data
- data to post. This can point to a JSON data file, or point directly to the XML file to be checked.Within the -d/--data parameter, the following properties are allowed
- id: user-generated, will be returned in response for parsing purposes on part of the user
- style: which stylechecker to use. Currently supported: pmc (default), pmc-nihms, pmc-books
- doc_name: name of xml document to be checked. The name will be returned in the response, for parsing purposes on part of the user
- digest_type: algorithm used to map document to a bit string. Currently only "md5" is supported
- digest: alpha hash string that represents the mapping created by digest_type.
- transcoding: gzip, base64 -- algorithm used to convert document into a string
- data: the document-as-string generated by the transcoding algorithm
-
-F/--form
- form upload. This uses the names of the form fields from the HTML version of the Style Checker. -F nxml=
(pasted text)-F url=
(URL pointing to file)-F pxml=
(XML file being checked)-F style=
(pmc [default], pmc-nihms, pmc-books)-F format=
(xml, json, html)-F transcoding=
(base64, plain)
Examples
Example 1: Upload a data file using -d/--data
. The data file can be either JSON or XML. In it, point to or provide the xml file to be checked.
JSON (using "url" param to point to the xml file to be checked)
curl -H "Content-Type: application/json" -d @data_file.json https://www.ncbi.nlm.nih.gov/pmc/utils/style4/v1.0/
where data_file.json looks like
{"id": "your-id",
"style": "pmc",
"doc_name": "test.xml",
"url": "url/to/test.xml",
"coding": "plain"}
XML (using <data>
element to hold the XML file as a base64-encoded string)
curl -H "Content-Type: text/xml" -d @data_file.xml https://www.ncbi.nlm.nih.gov/pmc/utils/style4/v1.0/
where data_file.xml looks like
<request>
<id>your-id</id>
<style>pmc</style>
<doc_name>test.xml</doc_name>
<transcoding>gzip,base64</transcoding>
<data>[content of test.xml encoded into base64 string]</data>
</request>
Example 2: Upload an XML file using -F/--form. This mimics the HTML version of the Style Checker.
curl -i -F style=pmc -F pxml=@test.xml -F transcoding=plain -F format=xml https://www.ncbi.nlm.nih.gov/pmc/utils/style4/v1.0/
Use the "format" field to specify the format of the response. Allowed values are "json" and "xml".
Response
JSON – NO ERROR or WARNING
{
"status": "ok",
"responseDate": "2021-09-02 15:42:00",
"request": "style=pmc-nihms;pxml=test.xml;transcoding=plain;format=json",
"dtd_valid": true,
"style_valid": true,
"messages": [
{
"status": "OK",
"caption": "DTD Validation",
"ctx": {
"transcoding": "plain",
"data": "...",
}
},
{
"status": "OK",
"caption": "NIH Manuscript Style Check",
"stat": {
"errors": "0",
"warnings": "0"
},
"ctx": {
"transcoding": "plain",
"data": "...",
}
}
]
}
JSON – INVALID
{
"status": "ok",
"responseDate": "2021-09-02 15:52:40",
"request": "POSTDATA=%7B%20%20%20%20%22id%22%3A%20%22ABCDE-FGHIJ-12345-67890%22%
2C%20%20%20%20%22style%22%3A%20%22pmc%22%2C%20%20%20%20%22doc_name%22%3A%20%22test.xml
%22%2C%20%20%20%20%20%22url%22%3A%20%22https%3A%2F%2Fwww.ncbi.nlm.nih.gov%2Fpmc%2Futils
%2Fstyle4%2Ftest%2Ftest.xml%22%2C%20%20%20%20%22coding%22%3A%20%22plain%22%09%7D",
"dtd_valid": true,
"style_valid": false,
"messages": [
{
"status": "OK",
"caption": "DTD Validation",
"ctx": {
"transcoding": "plain",
"data": "..."
}
},
{
"status": "Errors",
"caption": "PMC Style Check",
"stat": {
"errors": "2",
"warnings": "0"
},
"html": {
"transcoding": "plain",
"data": "..."
},
"ctx": {
"transcoding": "plain",
"data": "..."
},
"rawerrors": [
{
"message": {
"type": "error",
"text": "fpage-elocation check: Either <fpage> or <elocation-id> must
be present in <article-meta>
(Tagging Guidelines) see https:\/\/www.ncbi.nlm.nih.gov\/pmc\/pmcdoc\
/tagging-guidelines\/article\/tags.html#el-fpage"
}
},
{
"message": {
"type": "error",
"text": "pub-date check: article-meta must contain a real publication date."
}
}
]
}
]
}
XML – NO ERROR OR WARNING
<response status="ok">
<request outtype="xml">
<echo>style=pmc-nihms;pxml=test.xml;transcoding=plain;format=xml</echo>
</request>
<dtd_valid>true</dtd_valid>
<style_valid>true</style_valid>
<messages>
<msg status="OK" caption="DTD Validation">
<ctx><transcoding>plain</transcoding><data><![CDATA ... </data></ctx>
</msg>
<msg status="OK" caption="NIH Manuscript Style Check">
<stat errors="0" warnings="0"/>
<ctx><transcoding>plain</transcoding><data><![CDATA ... </data></ctx>
</msg>
</messages>
</response>
XML – INVALID
<response status="ok">
<request outtype="xml">
<echo>POSTDATA=%3Crequest%3E%20%20%3Cstyle%3Epmc%3C%2Fstyle%3E%20%20%3Cid%
3EABCDE-FGHIJ-12345-67890%3C%2Fid%3E%20%20%3Cdoc_name%3Etest.xml%3C%2Fdoc_name
%3E%20%20%3Curl%3Ehttps%3A%2F%2Fwww.ncbi.nlm.nih.gov
%2Fpmc%2Futils%2Fstyle4%2Ftest%2Ftest.xml%3C%2Furl%3E%20%20%3Ccoding
%3Eplain%3C%2Fcoding%3E%20%3C%2Frequest%3E</echo>
</request>
<dtd_valid>true</dtd_valid>
<style_valid>false</style_valid>
<messages>
<msg status="OK" caption="DTD Validation">
<ctx><transcoding>plain</transcoding><data><![CDATA ... </data></ctx>
</msg>
<msg status="Errors" caption="PMC Style Check">
<stat errors="2" warnings="0"/>
<html><transcoding>plain</transcoding><data><![CDATA ... </data></html>
<ctx><transcoding>plain</transcoding><data><![CDATA ... </data></ctx>
<rawerrors>
<message type="error">fpage-elocation check: Either <fpage> or
<elocation-id> must be present in <article-meta>
(Tagging Guidelines) see https://www.ncbi.nlm.nih.gov/pmc/pmcdoc/
tagging-guidelines/article/tags.html#el-fpage</message>
<message type="error">pub-date check: article-meta must contain a
real publication date.</message>
</rawerrors>
</msg>
</messages>
</response>