I/O and data

XML, YAML, Gson and Protobuf

Enterprise systems exchange data in many formats besides JSON: XML (SOAP, legacy and government feeds), YAML configuration, Gson in older code, and Protobuf for compact internal messages.

🔎 Unravel this example

At a glance

Mental model

Different languages for the same conversation.

What happens, in order

1XML: JAXB maps annotated classes (@XmlRootElement, @XmlElement) to and from XML through a JAXBContext with a Marshaller and UnmarshallerJackson XmlMapper offers the same with Jackson annotations. For huge files use streaming (StAX XMLStreamReader) instead of loading a DOM.
2Gson maps JSON with new Gson().toJson(obj) and fromJson(text, Type.class); field names are customised with @SerializedNameJackson is more common in Spring, but Gson appears in Android and older libraries.
3YAML (SnakeYAML, Jackson YAMLMapper) is for configuration; it is a superset of JSON with indentation rules
4Protobuf messages are generated from .proto files; Order.parseFrom(bytes) and order.toByteArray() convert them

Remember

XML parsers resolve external entities by default in many setups, which allows XXE attacks (reading local files or calling internal URLs)
Loading untrusted YAML with the default SnakeYAML constructor can instantiate arbitrary classes
DOM parsers build the whole tree in memory (heavy), SAX pushes events to callbacks, StAX lets your code pull tokens at its own pace, which is why StAX is the best choice for large inputs

Watch out

XML parsers with external entities enabledUnsafe YAML loadingCreating JAXBContext per requestLoading huge XML into DOM

Example (highlighted lines explain it)

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);DocumentBuilder builder = factory.newDocumentBuilder();Document doc = builder.parse(new InputSource(new StringReader(xml)));

line 1 uses DocumentBuilderFactory, the core of XML, YAML, Gson and Protobuf

Read the full explanation (about 2 min)

Enterprise systems exchange data in many formats besides JSON: XML (SOAP, legacy and government feeds), YAML configuration, Gson in older code, and Protobuf for compact internal messages. Each has its own tools and pitfalls.

A mental model

Different languages for the same conversation. The meaning is the same; the grammar, the cost of translation and the risks of mistranslation are not.

How it works

XML: JAXB maps annotated classes (@XmlRootElement, @XmlElement) to and from XML through a JAXBContext with a Marshaller and Unmarshaller. Jackson XmlMapper offers the same with Jackson annotations. For huge files use streaming (StAX XMLStreamReader) instead of loading a DOM.

Gson maps JSON with new Gson().toJson(obj) and fromJson(text, Type.class); field names are customised with @SerializedName. Jackson is more common in Spring, but Gson appears in Android and older libraries.

YAML (SnakeYAML, Jackson YAMLMapper) is for configuration; it is a superset of JSON with indentation rules.

Protobuf messages are generated from .proto files; Order.parseFrom(bytes) and order.toByteArray() convert them.

Going deeper

XML parsers resolve external entities by default in many setups, which allows XXE attacks (reading local files or calling internal URLs). Disable DTDs and external entities (FEATURE_SECURE_PROCESSING, disallow-doctype-decl) on every factory.

Loading untrusted YAML with the default SnakeYAML constructor can instantiate arbitrary classes. Use SafeConstructor or a LoaderOptions allow-list.

Gson and Jackson differ on nulls, unknown fields and numbers (Gson reads integers into Double in untyped maps). Do not switch libraries without tests on edge cases.

Under the hood

DOM parsers build the whole tree in memory (heavy), SAX pushes events to callbacks, StAX lets your code pull tokens at its own pace, which is why StAX is the best choice for large inputs. JAXB builds its binding metadata from annotations once per context, so creating JAXBContext repeatedly is very slow; cache it.

Common mistakes

XML parsers with external entities enabled.
Unsafe YAML loading.
Creating JAXBContext per request.
Loading huge XML into DOM.

How Unravel recognises it

When you paste code, Unravel looks for these signs of xml, yaml, gson and protobuf. Spotting them yourself is a good habit when you read unfamiliar code:

Annotations: @XmlRootElement @XmlElement @XmlAttribute @XmlAccessorType @XmlType @XmlTransient @JacksonXmlProperty @JacksonXmlRootElement
Types: Gson GsonBuilder XmlMapper JAXBContext Marshaller Unmarshaller XStream Yaml YAMLMapper YAMLFactory XMLInputFactory XMLStreamReader SAXParserFactory DocumentBuilderFactory and 7 more
Method calls: parseFrom()

Part of a learning path

Building and documenting APIs · previous: File upload and download · next: Java serialization and its risks

Related concepts

Jackson JSONI/O and data SOAP and JAX-WS web servicesI/O and data

Frequently asked questions

What is XML, YAML, Gson and Protobuf?

What are the most common mistakes with XML, YAML, Gson and Protobuf?

XML parsers with external entities enabled. Unsafe YAML loading. Creating JAXBContext per request. Loading huge XML into DOM.

How can I see XML, YAML, Gson and Protobuf in real code?

Paste your own Java into Unravel and it will point out where xml, yaml, gson and protobuf appears, explain how it works at the detail level you choose, and draw the flow of the code around it.