Foreign keys¶

A foreign key is served as the primary key of the row it references.

Given two models:

class Parent(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    geom = models.PointField(srid=4326)

class Child(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    geom = models.PointField(srid=4326)
    parent = models.ForeignKey(Parent, on_delete=models.CASCADE)

oapif.register_collection(Parent)
oapif.register_collection(Child)

A feature of the Child collection looks like this:

{
  "type": "Feature",
  "id": "8a4b3a52-5b0e-4bd4-9c8f-0c5b1f6f3f2e",
  "geometry": {
    "type": "Point",
    "coordinates": [0.0, 0.0]
  },
  "properties": {
    "id": "8a4b3a52-5b0e-4bd4-9c8f-0c5b1f6f3f2e",
    "parent": "2310f561-39a4-4393-844c-19c99a12f45d"
  }
}

Writes take the same primary key, in POST, PUT and PATCH. A key that references no row is rejected with a 422 Unprocessable Content:

{
  "detail": [
    {
      "loc": ["body", "feature", "properties", "parent"],
      "msg": "Foreign key not found",
      "type": "value_error"
    }
  ]
}

So is a key with the reference role to a row that the collections it references do not serve the user: a user cannot link a feature to one that get_queryset() hides from them, such as someone else's, nor tell it from a row that does not exist. A key that a PUT or a PATCH writes back unchanged is kept, though, even if its row is no longer served. A key without the role may reference any row of its model.

The reverse relations, the children of a parent here, are not served.

Schema¶

The schema of the collection gives the property the reference role of Part 5, with the collections of the referenced model that the user may view in x-ogc-collectionId: a single id, or a list when the model has several collections.

"parent": {
  "title": "Parent",
  "type": "string",
  "format": "uuid",
  "x-ogc-role": "reference",
  "x-ogc-collectionId": "my_app.parent",
  "x-ogc-propertySeq": 2
}

A key to a model without a collection, or to another field than its primary key, has no role.