Documenting XML is very similar to documenting JSON. Peter explains the differences between the two, especially regarding documenting atttributes. XML with a small number of attributes can explain those attributes in the Notes column. XML with a large number of attributes requires a separate attribute column. Like JSON, XML nesting can be documented with either indentation or multiple tables.
- [Instructor] Now let's go over how to document XML. Documenting XML is very similar to documenting JSON. In fact, many times an API can use both JSON and XML whereas in JSON an element was an object, in XML an element refers to a tag and what's contained inside that tag. Let me reiterate my caveat. There's no one standard way to document XML. What's described in this video is my favorite way based on years of experience. You might find a better way for the APIs that you document.
Again, I suggest documenting one XML file and then getting approval from the project manager and the developers before writing all of the documentation. As I mentioned before, it's very common that an API can handle data in both JSON and XML. When an API request is made, it specifies which format to use. What you don't want to do is create separate tables for JSON and for XML because that would be a lot of redundant information so try to create one table that can capture both.
To do this, use the same table columns that I described in the JSON lessons. If the API is designed well, then the key names in JSON and the tag names in XML should be the same. Also, the types should be identical. You would expect an element to be a string, a number or a Boolean in both JSON and XML. There are two kinds of types in XML, simple and complex. Simple types are just strings whereas complex types contain other tags. Although technically all simple types are strings, the software that reads the XML may convert that string into a number, Boolean, date, URL and so on so you need to document the type so that developers know what kind of conversion to use.
This applies to both content and attribute values. Complex types are elements that contain other elements. For these, list the element name in the type column. If you're documenting the XML file with multiple tables, then have a table for each element type. I'll show you an example of this later in the video. In many ways, the structure of JSON and XML are very similar. However, XML has the ability to put data values into two places, content and attributes, whereas JSON only has the one.
If an API uses both JSON and XML, then typically the XML does not have attributes so that there's a simpler mapping between the two data formats or at least it'll have very few attributes. Here are some guidelines for handling attributes. If you're documenting XML with only a few small number of attributes, then put the attribute information into the notes column. If you're documenting XML with many attributes, then add a column for attributes. Let me show you how that works. Let's take this song XML you've seen previously and add one simple attribute which is on the song tag.
It indicates with a two-character code what the language is. Here's the table that documents the XML. You can see that it looks very similar to the one we created for JSON. However, there are two important differences. The first is that the song element now has an attribute for language. I've added that into the notes column. The second is that the musician's array requires elements of type musician so I've added a row to capture that which is indented twice. Now let's rewrite that XML so that it uses more attributes.
In this version, instead of being tags, the song title, artist and musician name are all attributes. Here is what the documentation table would look like now. We only have three elements now, song, musicians and musician. There's a new column called attribute which contains tile, artist and name where each one is listed right after its respective element. Okay, there's one more documentation style I'd like to show you.
I'm sure you remember this XML that describes a menu user interface. I'll show you how to break it down into multiple tables. First note that at the top level, we have a menu element. The menu element contains multiple column elements. The column element contains a header element and multiple item elements. We're going to create a table for each type of element. So we'll create a top level table and put a menu element into it. In the type column, put a link that links to the next table.
Now going back to the XML, we can see that the menu item has one or more column elements inside of it so we'll create a table for that with a column element, a description that says you can have one or more columns and a link to the column element table. If you remember, the column element has a header tag and one or more item tags so the table has rows for each of these. The header is simply a string, but the item has its own tags so we need a link to an item table and we would need to create a table for that element as well.
One last thing to mention, create tables for requests and responses in a similar way as you did for JSON. In other words, the tables have the same columns, except that the tables for requests have an additional column called required. The required column should have values of either required or optional. If an element or attribute is optional, then put the default value into the notes column.
- The purpose of documentation
- Data types
- Structured data
- Writing JSON and XML
- Documenting one-level JSON responses
- Documenting nested JSON responses
- XML attributes and examples
- Documenting XML
- Structuring data documentation