Referencing vs Inlining

When one entity references another, for example, on the route.jobs field, the subobject (for example, job) can be specified inline as part of the parent object, or alternatively, the string ID of the referenced entity can be specified. The API expects to find the referenced entity on its top-level collection (for example, problem.jobs).

Note

When working with sandboxes, most entities must be specified by reference. See Canonical Form.

Marker Inlining

When string is specified for a marker (for example, on job.location), the string is first parsed to determine if it is a latlon. Any latlons are interpreted as inline markers at that latlon, instead of a marker reference by ID. Therefore, it is invalid for marker IDs to match the latlon format.

Examples

All Entities by Reference

Example of a problem file with all entities specified by reference:

{
	"id": "referencing_example",
	"routes": [
		{
			"id": "route0",
			"location": "route0_location", // reference to problem.markers
			"jobs": [ "job0", "job1", "job2" ] // reference to problem.jobs
		}
	],
	"jobs": [
		{ "id": "job0", "location": "marker0" }, // reference to problem.markers
		{ "id": "job1", "location": "marker1" }, // reference to problem.markers
		{ "id": "job2", "location": "marker2" }  // reference to problem.markers
	],
	"markers": [
		{ "id": "route0_location", "location": "12.000,-34.000" },
		{ "id": "marker0", "location": "12.001,-34.001" },
		{ "id": "marker1", "location": "12.002,-34.002" },
		{ "id": "marker2", "location": "12.003,-34.003" }
	]
}

Some Entities by Reference

The same problem file as above with markers represented inline:

{
	"id": "referencing_example",
	"routes": [
		{
			"id": "route0",
			"location": "12.000,-34.000", // inline marker
			"jobs": [ "job0", "job1", "job2" ] // reference to problem.jobs
		}
	],
	"jobs": [
		{ "id": "job0", "location": { "location": "12.001,-34.001" } }, // inline marker
		{ "id": "job1", "location": "12.002,-34.002" }, // inline marker, specified with a latlon string
		{ "id": "job2", "location": "12.003,-34.003" }  // inline marker, specified with a latlon string
	]
}

All entities inline

The same problem file as above with all entities represented inline:

{
	"id": "referencing_example",
	"routes": [
		{
			"id": "route0",
			"location": "12.000,-34.000", // inline marker
			"jobs": [
				{ "id": "job0", "location": { "location": "12.001,-34.001" } }, // inline job and marker
				{ "id": "job1", "location": "12.002,-34.002" }, // inline job and marker
				{ "id": "job2", "location": "12.003,-34.003" }  // inline job and marker
			]
		}
	]
}

See Also

• API Overview