Resource Update Samples

February 19, 2026 ยท View on GitHub

This document shows a set of write operations that provide concrete examples of how the Resource Processing Algorithm is applied based on the state of the Registry and the incoming request. They are meant to be read in order to avoid repeating the same commentary for each example.

Table of Contents

The Setup

Each example:

  • Only includes the key attributes that are important from an "understanding" perspective.
  • Includes explanatory text, highlighting the key aspects.
  • Timestamps will only use a year or "now" (meaning it was updated to the current time) rather than a full RFC3330 timestamp to make it easier to detect changes in values.
  • Has a model defined as:
        {
          "groups": {
            "dirs": {
              "singular": "dir",
              "resources": {
                "files": {
                  "singular": "file",
                  "hasdocument": false,
                  "versionmode": "createdat"
                }
              }
            }
          }
        }

Create single Resource with empty content

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{}

Final State:

{
  "fileid": "f1",
  "versionid": "1",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "1",
    "defaultversionsticky": false
  },
  "versions": {
    "1": { see Resource.* attrs }
  }
}

Notes:

  • A new Resource f1 is created.
  • A Version with a versionid of 1 is created per the default versionid naming algorithm defined in the specification.
  • Conceptually, this new Version is populated with the Resource's default Version attributes from the request. However, since there are none, all mandatory attributes are assigned their default values.
  • The Version's ancestor value is 1 (points to itself) because it is the root of a hierarchy tree.
  • Being the only Version, it is the default Version, and it is not "sticky".
  • Using PATCH instead of PUT will yield the exact same results.

Create Resource via the "files" collection

Initial State:

Empty

Request:

POST /dirs/d1/files

{
  "f1": {
    "name": "my file"
  }
}

Final State:

{
  "f1": {
    "fileid": "f1",
    "versionid": "1",
    "epoch": 1,
    "name": "my file",
    "isdefault": true,
    "createdat": "now",
    "modifiedat": "now",
    "ancestor": "1",

    "meta": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "defaultversionid": "1",
      "defaultversionsticky": false
    },
    "versions": {
      "1": { see Resource.* attrs }
    }
  }
}

Notes:

  • Similar to previous example, but creating the Resource via the owning Group's files collection.
  • The default Version properties include name, so that will appear both at the Resource level and within the Version in the versions collection.

Create Resource with Versions, no defaultversionid

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "versions": {
    "v1": {},
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
  }
}

Notes:

  • After creating the Resource, f1, Versions v1 and v2 are created.
  • Note that name will be ignored because when versionid and meta.defaultversionid are absent, but versions is not empty, all Resource.* attributes are ignored.
  • Since all Versions have the same createdat timestamp they are sorted alphabetically by their versionid values in order to set their ancestor attributes.
  • Which means v2 becomes the newest and therefore the default Version.
  • Ancestor order: 1 <- v1 <- v2.
  • Using PATCH would yield the exact same results.

Create Resource with Versions and defaultversionid

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "meta": {
    "defaultversionid": "v1"
  },
  "versions": {
    "v1": {
      "createdat": "2020"
    },
    "v2": {
      "createdat": "3030"
    },
    "v3": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "3030",
  "modifiedat": "now",
  "ancestor": "v3",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "createdat": "2020",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs },
    "v3": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    }
  }
}

Notes:

  • No Version 1 is created because we used meta.defaultversionid as a clue that Resource.* attributes are for v1.
  • Resource.* attributes (eg name) is ignored because v1 is part of the request's versions collection.
  • Ancestor order: v1(2020) <- v3 (now) <- v2 (3030).
  • Version v2 is default because it has the newest createdat timestamp.

Create Resource with Versions and unique defaultversionid

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "meta": {
    "defaultversionid": "v1"
  },
  "versions": {
    "v2": {},
    "v3": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v3",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v2",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v3",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "name": "foo",
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v3": { see Resource.* attrs },
  }
}

Notes:

  • No Version 1 is created because we used meta.defaultversionid as a clue that Resource.* attributes are for v1.
  • Resource.* attributes (eg name) are assigned to v1.
  • Ancestor order: v1(now) <- v2 (now) <- v3 (now).
  • Version v3 is default because it is the highest alphabetically.

Create Resource with defaultversionid

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "meta": {
    "defaultversionid": "v1"
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "foo",
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Notes:

  • Version v1 is created due to meta.defaultversionid being set.
  • Since v1 isn't part of the request's versions collection, the Resource.* attributes will be applied.

Create Resource with versionid and Versions

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "versionid": "v0",
  "name": "foo",
  "versions": {
    "v1": {
      "createdat": "2020"
    },
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v0",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v0": {
      "epoch": 1,
      "name": "foo"
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v1": {
      "epoch": 1,
      "createdat": "2020",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
  }
}

Notes:

  • Version v0 is created because it is not present in versions.
  • Ancestor order: v1 (2020) <- v0 (now) <- v2 (now).

Update Resource with new Versions and sticky default Version

Initial State:

{
  "fileid": "f1",
  "versionid": "v0",
  "epoch": 1
  "isdefault": true,
  "createdat": "2021",
  "modifiedat": "2021",
  "ancestor": "v0",

  "meta": {
    "epoch": 1,
    "createdat": "2021",
    "modifiedat": "2021",
    "defaultversionid": "v0",
    "defaultversionsticky": false
  },

  "versions": {
    "v0": { see Resource.* attrs }
  }
}

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "meta": {
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": {
      "createdat": "2020"
    },
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2020",
  "modifiedat": "now",
  "ancestor": "v0",

  "meta": {
    "epoch": 2,
    "createdat": "2021",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v0": {
      "epoch": 2,
      "name": "foo",
      "createdat": "2021",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v1": { see Resource.* attrs },
    "v2": { see Resource.* attrs }
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v0"
    }
  }
}

Notes:

  • Version v0 (the current default Version) is updated with the Resource.* attributes. Notice that versionid is not present in the request and that it isn't needed as a "clue" because the Resource already exists so we know what the current default Version is.
  • While meta.defaultversionid is not used as a clue as to the "current" default versionid, it will be used to calculate the resulting default Version due to defaultversionsticky being true.
  • Ancestor order: v1 (2020) <- v0 (2021) <- v2 (now).

Create Resource with Versions and sticky default Version

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "versionid": "v0",
  "name": "foo",
  "createdat": "2021",
  "meta": {
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": {
      "createdat": "2020"
    },
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2020",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v0": {
      "epoch": 1,
      "name": "foo",
      "createdat": "2021",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v1": { see Resource.* attrs }
    "v2": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v0"
    }
  }
}

Notes:

  • In this case versionid at the Resource level is needed to ensure that the current default Version is v0 and that it is created.
  • Notice that the 2 potential "clues" (versionid and meta.defaultversionid) have different values because we need to create v0 as the current default Version when processing the Resource.* attributes, but then assign v1 as the resulting default Version. This means that in the previous example versionid was not needed, but in this example it is to yield the correct (same) net result.
  • Ancestor order: v1 (2020) <- v0 (now) <- v2 (now).

Create Resource with versionid and defaultversionid

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "versionid": "v0",
  "name": "foo",
  "meta": {
    "defaultversionid": "v1"
  },
  "versions": {
    "v1": {
      "createdat": "2020"
    },
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v0",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v0": {
      "epoch": 1,
      "name": "foo",
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v1": {
      "epoch": 1,
      "createdat": "2020",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
  }
}

Notes:

  • Version v0 is created due to the presence of versionid. Which means meta.defaultversionid is ignored for the purpose of determining the current default Version. However, it is also ignored when calculating the resulting default Version due to defaultversionsticky being false.
  • Ancestor order: v1 (2020) <- v0 (now) <- v2 (now).

Create Resource with sticky defaultversionid

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "meta": {
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": {
      "createdat": "2020"
    },
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2020",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    }
  }
}

Notes:

  • In this case since versionid is not present, meta.defaultversionid will be used as the "clue" for the current default Version.
  • And, Version v1 will be the default and it's sticky.

Update Resource with non-sticky bad defaultversionid

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
      "createdat": "2025",
      "ancestor": "v1"
    }
  }
}

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "meta": {
    "defaultversionid": "abc"
  },
  "versions": {
    "v2": {
      "createdat": "2020"
    }
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "name": "foo",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v2",

  "meta": {
    "epoch": 2,
    "createdat": "2025",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
      "epoch": 2,
      "createdat": "2020",
      "modifiedat": "now",
      "ancestor": "v2"
    }
  }
}

Notes:

  • Current default Version is v1, and v1 is not in the request's versions collection, so it's "name" attribute is updated.
  • Version v2 is updated.
  • While meta.defaultversionid references a non-existing Version, no error is generated because its value is ignored due to meta.defaultversionsticky being false.
  • Ancestor order: v2 (2020) <- v1 (2025).

Update Resource with sticky non-specified defaultversionid

Initial State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "createdat": "2025",
      "modifiedat": "2025",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
    }
  }
}

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "meta": {
    "defaultversionsticky": true
  },
  "versions": {
    "v2": {
      "createdat": "2020"
    }
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v2",

  "meta": {
    "epoch": 2,
    "createdat": "2025",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
      "epoch": 2,
      "createdat": "2020",
      "modifiedat": "now",
      "ancestor": "v2"
    }
  }
}

Notes:

  • Notice that "Resource.name" is ignored because v2 (the current default Version) appears in the request's versions collection.
  • While the current default is v2, setting defaultversionsticky to true only takes effect after the default Version is recalculated. This is due to the fact that PUT is a complete replacement and meta.defaultversionid not being in the request is akin to setting it to null in the request. In the next example we'll see how PATCH changes this semantics.
  • Ancestor order: v2 (2020) <- v1 (2025).

Patch Resource with Versions and defaultversionsticky

Initial State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "createdat": "2025",
      "modifiedat": "2025",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
    }
  }
}

Request:

PATCH /dirs/d1/files/f1

{
  "name": "foo",
  "meta": {
    "defaultversionsticky": true
  },
  "versions": {
    "v2": {
      "createdat": "2020"
    }
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 2,
  "isdefault": true,
  "createdat": "2020",
  "modifiedat": "now",
  "ancestor": "v2",

  "meta": {
    "epoch": 2,
    "createdat": "2025",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": {
      "epoch": 2,
      "createdat": "2025",
      "modifiedat": "now",
      "ancestor": "v2"
    },
    "v2": { see Resource.* attrs }
  }
}

Notes:

  • Resource.name is ignored due to v2 (the current default Version) being in the request's versions collection.
  • Since this is a PATCH, unlike the previous example where meta.defaultversionid was implicitly set to null, in this case its value remains unchanged. So, when meta.defaultversionsticky is set to true the current default Version becomes "sticky".
  • Ancestor order: v2 (2020) <- v1 (2025).

Update Resource with empty content

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PUT /dirs/d1/files/f1

{}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Notes:

  • Notice that name is deleted because PUT is a complete replacement of all attributes.
  • No attributes in meta are updated.

Patch Resource with empty content

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },

  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PATCH /dirs/d1/files/f1

{}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Notes:

  • Notice this time name is unchanged due to the use of PATCH instead of PUT.
  • However, PATCH does update the epoch and modifiedat timestamps of the current default Version.
  • The meta sub-object is unchanged.

Update Resource with new description

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PUT /dirs/d1/files/f1

{
  "description": "very cool"
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "isdefault": true,
  "description": "very cool",
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Notes:

  • Default Version's name attribute is deleted.
  • Its description is updated.
  • Its epoch and modifiedat are automatically updated.
  • The meta sub-object is unchanged.

Patch Resource's description field

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PATCH /dirs/d1/files/f1

{
  "description": "very cool"
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "name": "my file",
  "isdefault": true,
  "description": "very cool",
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Notes:

  • Default Version's name attribute is unchanged.
  • Its description is updated.
  • Its epoch and modifiedat are automatically updated.
  • The meta sub-object is unchanged.

Update Resource with non-specified defaultversionsticky

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PUT /dirs/d1/files/f1

{
  "meta: {
    "defaultversionsticky": true
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 2,
    "createdat": "2025",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Notes:

  • The default Version's name attribute is deleted due to the operation being a PUT. Its epoch and modifiedat are automatically updated.
  • meta.defaultversionsticky is set to true, and since there is only one Version the calculated default Version remains 1.

Patch Resource with defaultversionsticky

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PATCH /dirs/d1/files/f1

{
  "meta: {
    "defaultversionsticky": true
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 2,
    "createdat": "2025",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Notes:

  • name is unchanged, but epoch and modifiedat are automatically updated.
  • As with previous example, Version 1 becomes sticky.
  • The default Version's name attribute is unchanged, but epoch and modifiedat are automatically updated.
  • meta.defaultversionsticky is set to true, and since there is only one Version the calculated default Version remains 1.

Patch Resource with sticky defaultversionid

Initial State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "createdat": "2025",
      "modifiedat": "2025",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
  }
}

Request:

PATCH /dirs/d1/files/f1/meta

{
  "defaultversionid": "v1",
  "defaultversionsticky": true
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 2,
    "createdat": "2025",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
      "epoch": 1,
      "createdat": "2025",
      "modifiedat": "2025",
      "ancestor": "v1"
    }
  }
}

Notes:

  • Notice the operation is directed to the meta sub-object, no attributes on Version v1 or v2 are modified.
  • However, per the request, the default Version is set to v1 and it is sticky.
  • The meta's epoch and modifiedat values are updated.
  • Ancestor order: v1 (2025) <- v2 (2025).

Patch Resource with bad defaultversionid

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PATCH /dirs/d1/files/f1

{
  "meta: {
    "defaultversionid": "foo"
  }
}

Final State:

Error due to `foo` being an unknown Version.

Notes:

  • While the request didn't set meta.defaultversionsticky to true explicitly, setting meta.defaultversionid via a PATCH implicitly sets meta.defaultversionsticky to true. If this operation used PUT instead, the error would not have been generated and meta.defaultversionid would have been ignored.

Update Resource with bad sticky defaultversionid

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "my file",
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { see Resource.* attrs }
  }
}

Request:

PUT /dirs/d1/files/f1

{
  "meta: {
    "defaultversionid": "foo",
    "defaultversionsticky": true
  }
}

Final State:

Error due to `foo` being an unknown Version.

Notes:

  • Similar to the previous example, except using PUT. If meta.defaultversionsticky had not been included in the request with a value of true then defaultversionid would have been ignored.

Update Resource with non-specified sticky default Version

Initial State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "isdefault": true,
  "createdat": "2025",
  "modifiedat": "2025",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "2025",
    "modifiedat": "2025",
    "defaultversionid": "v1",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": { ... }
  }
}

Request:

PUT /dirs/d1/files/f1

{
  "name": "foo",
  "createdat": "1999"
  "meta": {
    "defaultversionsticky": true
  },
  "versions": {
     "v2": { "createdat": "1998" }
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 2,
  "name": "foo",
  "isdefault": true,
  "createdat": "1999",
  "modifiedat": "now",
  "ancestor": "v2",

  "meta": {
    "epoch": 2,
    "createdat": "2025",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
       "epoch": 1,
       "createdat": "1998",
       "modifiedat": "now",
       "ancestor": "v2"
     }
  }
}

Notes:

  • Version v2 is created with a createdat value of 1998.
  • Version v1 is updated (name, createdat, epoch and modifiedat).
  • While v2 was just created, v1 is still the default Version because it has a newer createdat value. And it is now sticky per the request.
  • Ancestor order: v2 (1998) <- v1 (1999).

Create Resource with conflicting default Version attributes - variant 1

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "versionid": "v1",
  "name": "foo",
  "meta": {
    "defaultversionsticky": true
  },
  "versions": {
    "v1": {"name":"abc"},
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "name": "abc",
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
  }
}

Notes:

  • Resource.name is ignored because v1 is in request's versions collection.
  • Version v2 is default because it's the highest alphabetically.

Create Resource with conflicting default Version attributes - variant 2

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "meta": {
    "defaultversionid": "v1"
  },
  "versions": {
    "v1": {"name":"abc"},
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "name": "abc",
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
  }
}

Notes:

  • Resource.* attributes (implied "null" values because they're missing) are ignored because v1 is in the request's versions collection.
  • Version v2 is default because it's the highest alphabetically,
  • Despite meta.defaultversionid being specified, it is ignored when calculating the default Version because meta.defaultversionsticky is not true.

Create Resource with conflicting default Version attributes - variant 3

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1

{
  "versionid": "v1",
  "versions": {
    "v1": {"name":"abc"},
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v2",
  "epoch": 1,
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v2",
    "defaultversionsticky": false
  },
  "versions": {
    "v1": {
      "epoch": 1,
      "name": "abc",
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
    "v2": { see Resource.* attrs }
  }
}

Notes:

  • Same net results as previous example.

Create Resource with SetDefaultVersionID flag

Initial State:

Empty

Request:

PUT /dirs/d1/files/f1?setdefaultversionid=v1

{
  "versions": {
    "v1": {"name":"abc"},
    "v2": {}
  }
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "abc",
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
  }
}

Notes:

  • Use of the ?setdefaultversionid flag has the same semantics as setting meta.defaultversionid=v1 and meta.defaultversionsticky=true.

Create Resource with SetDefaultVersionID flag via /versions

Initial State:

Empty

Request:

POST /dirs/d1/files/f1/versions?setdefaultversionid=v1

{
  "v1": {"name":"abc"},
  "v2": {}
}

Final State:

{
  "fileid": "f1",
  "versionid": "v1",
  "epoch": 1,
  "name": "abc",
  "isdefault": true,
  "createdat": "now",
  "modifiedat": "now",
  "ancestor": "v1",

  "meta": {
    "epoch": 1,
    "createdat": "now",
    "modifiedat": "now",
    "defaultversionid": "v1",
    "defaultversionsticky": true
  },
  "versions": {
    "v1": { see Resource.* attrs },
    "v2": {
      "epoch": 1,
      "createdat": "now",
      "modifiedat": "now",
      "ancestor": "v1"
    },
  }
}

Notes:

  • Same net results as previous example.