The 'This Consists Of' Section of the Ingredient Listing

When SOD starts up, your recipe is checked to make sure it will work. Only certain items are allowed in certain places, so you have to be careful when creating or editing recipes.

The 'This Consists Of' section of the Ingredient Listing describes what should go where. We explain what the pieces are in terms of XML.

A Basic Example

This the 'This consists of' section of the origin point distance ingredient.

<originPointDistance>

<latitude>double</latitude>
<longitude>double</longitude>
range
</originPointDistance>

The containing originPointDistance tag

The first line shows the start tag <originPointDistance> . This means that at this point in the recipe (ie every place in the 'Places containing this' section) the element originPointDistance along with its contents are acceptable.

The next three lines along the black line must appear inside the originPointDistance element since they are directly below and indented from it. The black line indicates they are grouped together and must appear in the order they are given going down the page.

The latitude and longitude elements

The latitude element must be the first thing inside of the originPointDistance element. A latitude only contains one thing: a 'double'. Text without brackets in bold indicates a single piece of data. Anything that matches a generic datatype is acceptable here, and clicking on its link will take you to a description of the datatype. Since this is a 'double', pretty much any numeric value can be given.

After the latitude element and its 'double' contents, the very similar longitude element must be added to originPointDistance. It is just another element with a 'double' value inside of it.

Generic range definition

Finally, there is a link to 'range'. A simple link without any brackets should be replaced with the contents of its 'This consists of' section. To see what must go in the place of the range link, click on it to get to its page. It consists of a unit, min, and max element.

The unit element links to a deeper page that shows that it must be a complete unit element with the name of a unit of distance inside of it. As such, putting one of the values like KILOMETER or MILE satisfies this condition.

The min and max elements are very similar to the latitude and longitude elements defined earlier. They are just simple elements with doubles inside of them.

For this particular example, then, the range link in originPointDistance should be replaced with a unit element, a min element, and a max element.

Putting it all together

Combining the results of the previous section, originPointDistance consists of an originPointDistance tag with latitude, longitude, unit, min and max tags inside of it:

<originPointDistance>
    <latitude>35</latitude>
    <longitude>-85</longitude>
    <unit>DEGREE</unit>
    <min>30</min>
    <max>90</max>
</originPointDistance>

Labels

Compared to the last example, this one is a bit larger. It also has labels beside or surrounding certain tags to tell tell whats allowed and how many times. In particular, this example introduces the concepts of 'choice', 'optional', and 'Any number of times'. Both examples so far have used a 'group'.

group

A group is denoted by a solid vertical line. The concept of a group is simple, and we already followed it without naming it in the previous example. Tags in a group must appear in the order they are specified in the 'This consists of' section. This means that inside the eventFinder the name always comes first, then dns and so on down the line of the group.

choice

Choices are denoted by a dashed vertical line. Within a choice, you can use one of the items it contains. For this particular example, you have the choice between globalArea and boxArea. Also, if you follow the name and dns links, you will see that they also have choices for the values you may enter.

optional

Any tag or choice that is labeled as 'optional' can be included either once or not at all. For this example, you don't have to have an originDepthRange or a magnitudeRange if you don't need to use one. Since they are both in the group we talked about earlier, they must be included in the right order if they are included. If they are left out, you just skip to the next item in the group.

Any number of times

Anything labeled as 'Any number of times' is optional, but can be included more than once. In this example, you can have one catalog tag, 20 catalog tags, absolutely no catalog tags, or however many catalog tags you wish.

A Couple Other Important Examples

This is the 'This consists of' section of the eventRefreshInterval ingredient...

...and this is the 'This consists of' section of the requestOR ingredient.

Just a few more labels you need to know...

These last two examples illustrate a couple of other important concepts you need to know before you start looking up ingredients. These concepts are 'interleave' and 'At least once'.

interleave

An interleave is denoted by a dotted vertical line. It is similar to a choice, but its contents can be in any order. This is to say that, for the eventRefreshInterval example above, it doesn't matter whether or not the unit tag comes first. Both of the following xml snippets are acceptable.

<eventRefreshInterval>
  <value>30</value>
  <unit>HOUR</unit>
</eventRefreshInterval>
<eventRefreshInterval>
  <unit>HOUR</unit>
  <value>30</value>
</eventRefreshInterval>

At least once

Anything labeled 'At least once' is required, but can be included one or more times. In the requestOR example, requestOR must have at least one request. It cannot be empty, but it can have one, two, twenty, or an infinite amount of requests.