Trouble Understanding How to Make a NamedExample and DataType of JSON Objects

So my problem boils down to this. I have input that is formatted like so in JSON:

{"employee":{"id":"A007","first_name":"Jan","last_name":"Doe"}}

It can also come in like this, as an array:

{"employee":[{"id":"A007","first_name":"Jan","last_name":"Doe"},{"id":"A008","first_name":"Ron",
"last_name":"David"},{"id":"A009","first_name":"Jane","last_name":"Kane"},{"id":"A010","first_name":
"Marsh","last_name":"Megan"},{"id":"A011","first_name":"Kelly","last_name":"Mitch"},{"id":"A012",
"first_name":"Chris","last_name":"Vaste"}]}

The output will be handled later and will use the values of these objects.

I’m trying to make a NamedExample and DataType to handle the first input and for whatever reason, I can’t seem to be able to figure it out. Here’s my code so far:


RAML2
RAML3

I know I’m making some sort of mistake in either the DataType or the NamedExample, but the NamedExample is the one that keeps giving me an error. Specifically:

should have required property 'first_name'
should have required property 'id'
should have required property 'last_name'

I have looked all over the internet, went through the specifications, and I can’t seem to find a good example to help me move forward. I’m sure it really simple, but any help would be greatly appreciated.

So, I figured it out. There are couple ways you can approach this, but the requirements for this project specifically asked for us not to define types in the API specification. My implementation may not be the absolute best, however, I made second DataType and called it employees for now, though that will likely change. Here’s what that looks like:

RAML4

Basically, the object is the employee object contained within the employee class. Seems like a roundabout way to do this, so if anyone has any suggestions, I’ve got open eyes and ears.

@luckymcbeast: the content of NamedExample fragments is the same as the value of the examples (plural) node:

A declaration of the examples facet, whose key is a name of an example and whose value describes the example

(see “Typed Fragments” section of the RAML 1.0 spec)

This guide may also help as it provides different use cases along with some practical examples.

1 Like

Thanks, I think I understand that. I was more confused by handling a JSON object of the exact format of the one shown in my post. It seemed to require two NamedExamples for it to work. Is there a way to do it on just one NamedExample or an examples facet in general?

{"employee":{"id":"A007","first_name":"Jan","last_name":"Doe"}}

As you can see in the guide I linked to in my previous message, it’s possible to define single examples using the example (singular) node. Those examples can be defined in-line or externally by way of !include. Those examples cannot be typed fragments though as only the NamedExample fragment relates to examples and that fragment can only be !included in the examples node. That being said, a NameExample fragment can contain a single example, the only requirement is that it follows the rules of the examples node, that is it needs to have the name of the example as the root key of that node.

Any example, whether defined as example (singular) or examples (plural) can be defined as in-line JSON objects as long as it is properly defined (read: YAML-compliant).

Okay, I think I understand. So I can’t use the typed fragment NamedExample for this object because it requires more than one example, but I can make a general fragment and call it the same way I did before, with both examples on the same file.