RFC 3253
Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)
RFC 3253: Versioning Extensions to WebDAV 📜✨
okay bestie, let's start with the vibe check 💅. This is RFC 3253, and it's titled Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning) 🎀. It was written by G. Clemm (Rational Software), J. Amsden (IBM), T. Ellison (IBM), C. Kaler (Microsoft), and J. Whitehead (U.C. Santa Cruz) 👑. It's on the Standards Track, dated March 2002, and this title block doesn't list anything it obsoletes or updates 🦋. So it's a fresh, original spec, no drama 🫶.
Status of this Memo 🌸
okay so this doc is an Internet standards track protocol for the Internet community 💖. It's basically asking everyone to talk about it and send over suggestions for making it better 🧚. If you want to know where this protocol stands officially, go check the current edition of the "Internet Official Protocol Standards" (STD 1) 📖. And the best part? Distribution of this memo is unlimited 🌈. Share it with everyone, no gatekeeping 💅.
Copyright Notice 💜
Copyright (C) The Internet Society (2002). All Rights Reserved. 🔒✨
Abstract 🦋
this is the main character summary 🎀. The document defines a set of methods, headers, and resource types that make up the WebDAV versioning extensions to the HTTP/1.1 protocol 💅. The whole point is to keep clients simple 🍓. Clients that can work with a bunch of different versioning repository managers shouldn't need a ton of complicated code, and that makes it way easier for apps that use WebDAV versioning to get deployed everywhere 🚀✨.
It's a lot of features, and honestly it's giving everything 😭. WebDAV versioning covers:
- automatic versioning for clients that don't know anything about versioning 🤖
- version history management 📚
- workspace management 🗂️
- baseline management 📍
- activity management 🏃♀️
- URL namespace versioning 🔗
iconic, right? 👑
Table of Contents 🧚
The table of contents is up next, so stay tuned, bestie 💖🫶
Heads up, bestie: the text you pasted is only the table of contents, so I don't have the actual body of RFC 3253 to rewrite. Here's the part 2 skeleton with every section and subsection number and name, in order, so the structure lines up. Paste the body text and I'll fill in each section properly 💖
1. Introduction ✨
1.1. Relationship to WebDAV
1.2. Notational Conventions
1.3. Terms
1.4. Property Values
1.4.1. Initial Property Value
1.4.2. Protected Property Value
1.4.3. Computed Property Value
1.4.4. Boolean Property Value
1.4.5. DAV:href Property Value
1.5. DAV Namespace XML Elements
1.6. Method Preconditions and Postconditions
1.6.1. Example - CHECKOUT request
1.7. Clarification of COPY Semantics with Overwrite:T
1.8. Versioning Methods and Write Locks
2. Basic Versioning Features
2.1. Basic Versioning Packages
2.2. Basic Versioning Semantics
2.2.1. Creating a Version-Controlled Resource
2.2.2. Modifying a Version-Controlled Resource
2.2.3. Reporting
3. Version-Control Feature
3.1. Additional Resource Properties
3.1.1. DAV:comment
3.1.2. DAV:creator-displayname
3.1.3. DAV:supported-method-set (protected)
3.1.4. DAV:supported-live-property-set (protected)
3.1.5. DAV:supported-report-set (protected)
3.2. Version-Controlled Resource Properties
3.2.1. DAV:checked-in (protected)
3.2.2. DAV:auto-version
3.3. Checked-Out Resource Properties
3.3.1. DAV:checked-out (protected)
3.3.2. DAV:predecessor-set
3.4. Version Properties
3.4.1. DAV:predecessor-set (protected)
3.4.2. DAV:successor-set (computed)
3.4.3. DAV:checkout-set (computed)
3.4.4. DAV:version-name (protected)
3.5. VERSION-CONTROL Method
3.5.1. Example - VERSION-CONTROL
3.6. REPORT Method
3.7. DAV:version-tree Report
3.7.1. Example - DAV:version-tree Report
3.8. DAV:expand-property Report
3.8.1. Example - DAV:expand-property
3.9. Additional OPTIONS Semantics
3.10. Additional PUT Semantics
3.11. Additional PROPFIND Semantics
3.12. Additional PROPPATCH Semantics
3.13. Additional DELETE Semantics
3.14. Additional COPY Semantics
3.15. Additional MOVE Semantics
3.16. Additional UNLOCK Semantics
4. Checkout-In-Place Feature
4.1. Additional Version Properties
4.1.1. DAV:checkout-fork
4.1.2. DAV:checkin-fork
4.2. Checked-Out Resource Properties
4.2.1. DAV:checkout-fork
4.2.2. DAV:checkin-fork
4.3. CHECKOUT Method
4.3.1. Example - CHECKOUT
4.4. CHECKIN Method
4.4.1. Example - CHECKIN
4.5. UNCHECKOUT Method
4.5.1. Example - UNCHECKOUT
4.6. Additional OPTIONS Semantics
5. Version-History Feature
5.1. Version History Properties
5.1.1. DAV:version-set (protected)
5.1.2. DAV:root-version (computed)
5.2. Additional Version-Controlled Resource Properties
5.2.1. DAV:version-history (computed)
5.3. Additional Version Properties
5.3.1. DAV:version-history (computed)
5.4. DAV:locate-by-history Report
5.4.1. Example - DAV:locate-by-history Report
5.5. Additional OPTIONS Semantics
5.6. Additional DELETE Semantics
5.7. Additional COPY Semantics
5.8. Additional MOVE Semantics
5.9. Additional VERSION-CONTROL Semantics
5.10. Additional CHECKIN Semantics
6. Workspace Feature
6.1. Workspace Properties
6.1.1. DAV:workspace-checkout-set (computed)
6.2. Additional Resource Properties
6.2.1. DAV:workspace (protected)
6.3. MKWORKSPACE Method
6.3.1. Example - MKWORKSPACE
6.4. Additional OPTIONS Semantics
6.4.1. Example - OPTIONS
6.5. Additional DELETE Semantics
6.6. Additional MOVE Semantics
6.7. Additional VERSION-CONTROL Semantics
6.7.1. Example - VERSION-CONTROL
7. Update Feature
7.1. UPDATE Method
7.1.1. Example - UPDATE
7.2. Additional OPTIONS Semantics
8. Label Feature
8.1. Additional Version Properties
8.1.1. DAV:label-name-set (protected)
8.2. LABEL Method
8.2.1. Example - Setting a label
8.3. Label Header
8.4. Additional OPTIONS Semantics
8.5. Additional GET Semantics
8.6. Additional PROPFIND Semantics
8.7. Additional COPY Semantics
8.8. Additional CHECKOUT Semantics
8.9. Additional UPDATE Semantics
9. Working-Resource Feature
9.1. Additional Version Properties
9.1.1. DAV:checkout-fork
9.1.2. DAV:checkin-fork
9.2. Working Resource Properties
9.2.1. DAV:auto-update (protected)
9.2.2. DAV:checkout-fork
9.2.3. DAV:checkin-fork
9.3. CHECKOUT Method (applied to a version)
9.3.1. Example - CHECKOUT of a version
9.4. CHECKIN Method (applied to a working resource)
9.4.1. Example - CHECKIN of a working resource
9.5. Additional OPTIONS Semantics
9.6. Additional COPY Semantics
9.7. Additional MOVE Semantics
10. Advanced Versioning Features
10.1. Advanced Versioning Packages
10.2. Advanced Versioning Terms
11. MERGE Feature
11.1. Additional Checked-Out Resource Properties
11.1.1. DAV:merge-set
11.1.2. DAV:auto-merge-set
11.2. MERGE Method
11.2.1. Example - MERGE
11.3. DAV:merge-preview Report
11.3.1. Example - DAV:merge-preview Report
11.4. Additional OPTIONS Semantics
11.5. Additional DELETE Semantics
11.6. Additional CHECKIN Semantics
12. Baseline Feature
12.1. Version-Controlled Configuration Properties
12.1.1. DAV:baseline-controlled-collection (protected)
12.2. Checked-Out Configuration Properties
12.2.1. DAV:subbaseline-set
12.3. Baseline Properties
12.3.1. DAV:baseline-collection (protected)
12.3.2. DAV:subbaseline-set (protected)
12.4 Additional Resource Properties............................... 79
12.4.1 DAV:version-controlled-configuration (computed)........... 79
12.5 Additional Workspace Properties.............................. 80
12.5.1 DAV:baseline-controlled-collection-set (computed)......... 80
12.6 BASELINE-CONTROL Method...................................... 80
12.6.1 Example - BASELINE-CONTROL................................ 82
12.7 DAV:compare-baseline Report.................................. 84
12.7.1 Example - DAV:compare-baseline Report..................... 85
12.8 Additional OPTIONS Semantics................................. 86
12.9 Additional MKCOL Semantics................................... 86
12.10 Additional COPY Semantics................................... 86
12.11 Additional CHECKOUT Semantics............................... 86
12.12 Additional CHECKIN Semantics................................ 86
12.13 Additional UPDATE Semantics................................. 87
12.14 Additional MERGE Semantics.................................. 89
13 Activity Feature.............................................. 90
13.1 Activity Properties.......................................... 91
13.1.1 DAV:activity-version-set (computed)....................... 91
13.1.2 DAV:activity-checkout-set (computed)...................... 92
13.1.3 DAV:subactivity-set....................................... 92
13.1.4 DAV:current-workspace-set (computed)...................... 92
13.2 Additional Version Properties................................ 92
13.2.1 DAV:activity-set.......................................... 93
13.3 Additional Checked-Out Resource Properties................... 93
13.3.1 DAV:unreserved............................................ 93
13.3.2 DAV:activity-set.......................................... 93
13.4 Additional Workspace Properties.............................. 93
13.4.1 DAV:current-activity-set.................................. 94
13.5 MKACTIVITY Method............................................ 94
13.5.1 Example - MKACTIVITY...................................... 95
13.6 DAV:latest-activity-version Report........................... 95
13.7 Additional OPTIONS Semantics................................. 96
13.8 Additional DELETE Semantics.................................. 96
13.9 Additional MOVE Semantics.................................... 97
13.10 Additional CHECKOUT Semantics............................... 97
13.10.1 Example - CHECKOUT with an activity...................... 98
13.11 Additional CHECKIN Semantics................................ 99
13.12 Additional MERGE Semantics.................................. 99
14 Version-Controlled-Collection Feature.........................100
14.1 Version-Controlled Collection Properties.....................102
14.1.1 DAV:eclipsed-set (computed)...............................102
14.2 Collection Version Properties................................103
14.2.1 DAV:version-controlled-binding-set (protected)............103
14.3 Additional OPTIONS Semantics.................................103
14.4 Additional DELETE Semantics..................................103
14.5 Additional MKCOL Semantics...................................104
14.6 Additional COPY Semantics....................................104
14.7 Additional MOVE Semantics....................................104
14.8 Additional VERSION-CONTROL Semantics.........................104
14.9 Additional CHECKOUT Semantics................................105
14.10 Additional CHECKIN Semantics................................105
14.11 Additional UPDATE and MERGE Semantics.......................106
15 Internationalization Considerations...........................106
16 Security Considerations.......................................107
16.1 Auditing and Traceability....................................107
16.2 Increased Need for Access Control............................108
16.3 Security Through Obscurity...................................108
16.4 Denial of Service............................................108
17 IANA Considerations...........................................109
18 Intellectual Property.........................................109
19 Acknowledgements..............................................109
20 References....................................................110
Appendix A - Resource Classification..............................111
A.1 DeltaV-Compliant Unmapped URL.................................111
A.2 DeltaV-Compliant Resource.....................................111
A.3 DeltaV-Compliant Collection...................................112
A.4 Versionable Resource..........................................112
A.5 Version-Controlled Resource...................................112
A.6 Version.......................................................113
A.7 Checked-In Version-Controlled Resource........................113
A.8 Checked-Out Resource..........................................113
A.9 Checked-Out Version-Controlled Resource.......................114
A.10 Working Resource.............................................114
A.11 Version History..............................................114
A.12 Workspace....................................................115
A.13 Activity.....................................................115
A.14 Version-Controlled Collection................................115
A.15 Collection Version...........................................115
A.16 Version-Controlled Configuration.............................116
A.17 Baseline.....................................................116
A.18 Checked-Out Version-Controlled Configuration.................116
Authors' Addresses................................................117
Full Copyright Statement..........................................1181. Introduction ✨
okay bestie, so this spec is all about the WebDAV versioning extensions to HTTP/1.1 🦋. It defines a set of methods, headers, and properties that make versioning happen. Versioning is basically about tracking and accessing the history of important states of a web resource, like a standalone web page 📚. The benefits in the web world are honestly iconic:
- A resource gets an explicit history and a persistent identity across all the different states it's been in during that history. You can browse through past and alternative versions of it 🕰️. Often the modification and authorship history is the critical info all by itself 💅.
- Resource states (versions) get stable names, which can support externally stored links for annotation and link server support 🔗. Annotation and link servers often need stable references to parts of resources they don't directly control. Stable states give you stable pointers into those resources, plus well defined methods to figure out how those states are related ✨.
WebDAV Versioning defines both basic and advanced versioning functionality, and both are lowkey slay 👑.
Basic versioning lets users:
- Put a resource under version control 🎀
- Determine whether a resource is under version control 🔍
- Determine whether a resource update will automatically be captured as a new version 📸
- Create and access distinct versions of a resource 🌸
Advanced versioning brings the extra stuff for parallel development and configuration management of sets of web resources 🧚.
Here's the plan: the doc goes first with the properties and method semantics for the basic features, then covers the additional properties and method semantics for the advanced features 💖. If you're only into basic versioning, you can skip the advanced sections (Section 10 to Section 14). No shade, just save your brain 🫶.
1.1. Relationship to WebDAV
To get the most interoperability and use the protocol functionality that already exists 🤝, versioning support is built as extensions to the WebDAV protocol [RFC2518], which is itself an extension to the HTTP protocol [RFC2616]. All method marshalling and postconditions defined by RFC 2518 and RFC 2616 keep on holding, so versioning unaware clients can still interoperate successfully with versioning servers 🥹. The versioning extensions are designed to be orthogonal to most aspects of WebDAV and HTTP, but a clarification to RFC 2518 is required for effective interoperable versioning. That clarification is described in Section 1.7 📝.
1.2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 💜. Those are the rules of the game, bestie 🎮.
The term "protected" goes in parentheses after the definition of a protected property (see Section 1.4.2) 🔒.
The term "computed" goes in parentheses after the definition of a computed property (see Section 1.4.3) 🧮.
When an XML element type in the "DAV:" namespace is referenced in this document outside of the context of an XML fragment, the string "DAV:" gets prefixed to the element type 🏷️.
When a method is defined in this document, a list of preconditions and postconditions comes with it 📋. If the semantics of an existing method is being extended, you get a list of additional preconditions and postconditions instead 🧩. A precondition or postcondition is prefixed by a parenthesized XML element type that identifies it (see Section 1.6). It's giving organized 💅✨.
1.3. Terms ✨
okay so this section is basically the vocab list 📚 bestie, and it uses the terms from RFC 2616 and RFC 2518 plus a few new ones defined right here. Section 2.2 explains the semantic versioning model that all of this is built on, so you'll want to peek there too 💅
Version Control, Checked-In, Checked-Out 🔒
"Version control" is a set of constraints on how a resource can be updated. A resource under version control is either in a "checked-in" or "checked-out" state, and the version control constraints apply only while the resource is in the checked-in state. 🫶
Versionable Resource 🎀
A "versionable resource" is a resource that can be put under version control. Cute and simple 🌸
Version-Controlled Resource 🦋
When a versionable resource gets put under version control, it becomes a "version-controlled resource" ✨ A version-controlled resource can be "checked out" so its content or dead properties can be modified using standard HTTP and WebDAV methods.
Checked-Out Resource 🍓
A "checked-out resource" is just a resource under version control that's currently in the checked-out state. Easy peasy 💖
Version Resource 🧚
A "version resource", or simply "version", is a resource that holds a copy of one particular state (content and dead properties) of a version-controlled resource. A version gets created by "checking in" a checked-out resource. The server gives every new version its own distinct new URL, and that URL will never be used to identify any resource other than that version 🔥 The content and dead properties of a version never change, ever. Iconic, honestly 👑
Version History Resource 📜
A "version history resource", or simply "version history", is a resource that contains all the versions of one particular version-controlled resource. It's the whole family tree 🌳
Version Name 🏷️
A "version name" is a string the server picks to tell one version in a version history apart from the others in that same history. Versions from different version histories are allowed to share the same version name, so don't panic if you spot a duplicate 🙈
Predecessor, Successor, Ancestor, Descendant 🧬
When a version-controlled resource gets checked out and then checked back in, the version that was checked out becomes a "predecessor" of the version that the checkin creates. A client can specify multiple predecessors for a new version if that new version is logically a merge of those predecessors. When a version is connected to another version by traversing one or more predecessor relations, it's called an "ancestor" of that version. The flip side of predecessor and ancestor are "successor" and "descendant". So if X is a predecessor of Y, then Y is a successor of X, and if X is an ancestor of Y, then Y is a descendant of X. It's giving circle of life 🦁
Root Version Resource 🌱
The "root version resource", or simply "root version", is the version in a version history that is an ancestor of every other version in that version history. It's the OG, the starting point of the whole thread 👑
Workspace Resource 🏠
A "workspace resource", or simply "workspace", is a collection that contains at most one version-controlled resource for a given version history (see Section 6). Think of it as your cozy little room with one copy of each thing 🛋️
Working Resource 🛠️
A "working resource" is a checked-out resource that the server creates at a server-defined URL when a version (instead of a version-controlled resource) gets checked out. Here's the twist: unlike a checked-out version-controlled resource, a working resource is deleted when it's checked in. Poof 💨
Fork, Merge 🍴
When a second successor is added to a version, that creates a "fork" in the version history. When a version gets created with multiple predecessors, that creates a "merge" in the version history. A server may restrict the version history to be linear (with no forks or merges), but an interoperable versioning client should be prepared to deal with both forks and merges in the version history. So servers can keep things tidy, but clients need to be ready for the messy stuff too 🫣
The following diagram illustrates several of the previous definitions. Each box represents a version, and each line between two boxes represents a predecessor/successor relationship. For example, it shows V3 is a predecessor of V5, V7 is a successor of V5, V1 is an ancestor of V4, and V7 is a descendant of V4. It also shows that there is a fork at version V2 and a merge at version V7. Look at this family tree 😭
History of foo.html
+---+
Root Version -------> | | V1
+---+ ^
| |
| |
+---+ |
Version Name ----> V2 | | | Ancestor
+---+ |
/ \ |
/ \ |
+---+ +---+
| | V3 | | V4
^ +---+ +---+
| | | |
Predecessor | | | |
+---+ +---+ |
| | V5 | | V6 | Descendant
+---+ +---+ |
Successor | \ / |
| \ / |
v +---+ v
| | V7
+---+Label 🏷️
A "label" is a name that can be used to select a version from a version history. A label can be assigned by either a client or the server, and the same label can be used in different version histories. Labels are like nicknames, and the same nickname can show up in different friend groups 🥰
1.4. Property Values 🎀
1.4.1. Initial Property Value 🌷
Unless this document defines an initial value for a property of a given type, the initial value of a property of that type is implementation dependent. So it's up to the implementation, no drama 🤷♀️
1.4.2. Protected Property Value 🔐
When a property of a specific kind of resource is "protected", the property value cannot be updated on that kind of resource except by a method that's explicitly defined as updating that specific property. In particular, a protected property cannot be updated with a PROPPATCH request. Also, a given property can be protected on one kind of resource but not protected on another kind of resource. Protected means protected, but only in the spot it's protected 🛡️
1.4.3. Computed Property Value 🧮
When a property is "computed", its value is defined in terms of a computation based on the content and other properties of that resource, or even of some other resource. When the semantics of a method are defined in this document, the effect of that method on non-computed properties will be specified. The effect of that method on computed properties will not be specified, but it can be inferred from the computation defined for those properties. A computed property is always a protected property. Math with vibes 🧠✨
1.4.4. Boolean Property Value ✅
Some properties take a Boolean value of either "false" or "true". Simple, iconic, no notes 💅
1.4.5. DAV:href Property Value 🔗
The DAV:href XML element is defined in RFC 2518, Section 12.3. Go check it out if you want the full story 🧐
1.5. DAV Namespace XML Elements in Request and Response Bodies 📦
Request and response bodies in WebDAV can be extended with arbitrary XML elements, and the message recipient can ignore those. But an XML element in the DAV namespace MUST NOT be used in the request or response body of a versioning method unless that XML element is explicitly defined in an IETF RFC. So the DAV namespace is kind of VIP, and it only lets in the guests with a real invite 🚪💀
1.6. Method Preconditions and Postconditions 🧾
A "precondition" of a method describes the state of the server that must be true for that method to be performed. A "postcondition" of a method describes the state of the server that must be true after that method has been completed. If a method precondition or postcondition for a request is not satisfied, the response status of the request MUST be either 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request. So 403 means "don't bother, it's never gonna work" and 409 means "fix it and try again" 💁♀️
To help clients handle 403 and 409 responses better, a distinct XML element type is associated with each method precondition and postcondition of a request. When a particular precondition is not satisfied, or a particular postcondition can't be achieved, the appropriate XML element MUST be returned as the child of a top-level DAV:error element in the response body, unless the request has otherwise negotiated it. In a 207 Multi-Status response, the DAV:error element would appear in the appropriate DAV:responsedescription element. Every error gets its own named little tag, which is honestly so organized 📋💖
1.6.1. Example - CHECKOUT request with DAV:must-be-checked-in response 🙋♀️
Here's the request and response:
>>REQUEST
CHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
>>RESPONSE
HTTP/1.1 409 Conflict
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:error xmlns:D="DAV:">
<D:must-be-checked-in/>
</D:error>In this example, the request to CHECKOUT /foo.html fails because /foo.html is not checked in. The server basically says "wait, check this in first" 🙃
1.7. Clarification of COPY Semantics with Overwrite:T 🪞
RFC 2518, Section 8.8.4 states:
"If a resource exists at the destination and the Overwrite header is "T" then prior to performing the copy the server MUST perform a DELETE with "Depth: infinity" on the destination resource."
The purpose of this sentence is to make sure that after a COPY, all destination resources have the same content and dead properties as the corresponding resources identified by the request-URL. (A resource with a given name relative to the Destination URL "corresponds" to a resource with the same name relative to the request-URL.) If, at the time of the request, there already is a resource at the destination that has the same resource type as the corresponding resource at the request-URL, that resource MUST NOT be deleted. Instead it MUST be updated to have the content and dead properties of its corresponding member. If a client wants all resources at the destination deleted before the COPY, it MUST explicitly issue a DELETE request. So updating and replacing are not the same vibe 💞
The difference between updating a resource and replacing it with a new resource matters a lot when resource history is being maintained. Updating adds to an existing history, while replacing creates a new history. Also, locking and access control constraints might let you update a resource but not let you delete it and create a new one in its place. Protected chaos 🔒✨
Note that this clarification does not apply to a MOVE request. A MOVE request with Overwrite:T MUST perform the DELETE with "Depth:infinity" on the destination resource before performing the MOVE. MOVE is the exception, bestie, so don't mix them up 🫶
1.8. Versioning Methods and Write Locks 🔐💜
If a write-locked resource has a non-computed property defined by this document, the property value MUST NOT be changed by a request unless the appropriate lock token is included in the request. Since every method introduced in this document other than REPORT modifies at least one property defined by this document, every versioning method other than REPORT is affected by a write lock. In particular, the method MUST fail with a 423 (Locked) status if the resource is write-locked and the appropriate token is not specified in an If request header. So the lock is basically the bouncer, and no token means no entry 🚫🎟️
2. Basic Versioning Features 🦋
Each basic versioning feature defines extensions to existing HTTP and WebDAV methods, and it also defines new resource types, live properties, and methods. So each feature levels up the protocol in its own way ⭐
2.1 Basic Versioning Packages ✨
okay bestie, so a server MAY support any combination of versioning features 💅 but to keep a WebDAV basic versioning client from getting too complicated, a WebDAV basic versioning server SHOULD support one of these three "packages" (feature sets) 🎀
- Core-Versioning Package:
version-control - Basic-Server-Workspace Package:
version-control,workspace,version-history,checkout - Basic-Client-Workspace Package:
version-control,working-resource,update,label
The core-versioning package supports linear versioning for both versioning-aware and versioning-unaware clients 🦋 A versioning-aware client can use reports and properties to get at previous versions of a version-controlled resource. So cute, right? 🥰
The basic workspace packages are all about parallel development of version-controlled resources 🌈 Each client gets its own configuration of the shared version-controlled resources, and it can change its configuration without messing up anyone else's. No drama 🙈
In the basic-server-workspace package, all persistent state lives on the server 🧚 Each client gets its own workspace resource allocated on the server, and each workspace identifies one configuration of the shared version-controlled resources. Clients make changes to their workspace and can transfer changes from one workspace to another when it makes sense. This package is a great fit for clients with no local persistent state, or for clients that want to show their working configurations to other clients 👑
In the basic-client-workspace package, each client keeps the state for its configuration of the shared version-controlled resources in local persistent storage 💜 When a client is ready to make its changes visible to everyone, it allocates a set of "working resources" on the server, updates the content and dead properties of those working resources, and then uses them to update the version-controlled resources. Why the detour? Because the working resources are used instead of directly updating the version-controlled resources, so several clients can prepare sets of consistent updates in parallel ✨ Also, a working resource lets a client prepare a single update that takes multiple server requests (for example, updating both the content and dead properties of a resource needs both a PUT and a PROPPATCH) 🫶 The client workspace package keeps the server implementation simple by making each client maintain its own namespace. The tradeoff is that clients need local persistent state, and clients can't expose their working configurations to other clients 😭
A server that supports both basic workspace packages will interoperate with all basic versioning clients 🎀 Iconic.
2.2 Basic Versioning Semantics 🌸
2.2.1 Creating a Version-Controlled Resource 💖
okay so, to track the history of the content and dead properties of a versionable resource, a user can put that resource under version control with a VERSION-CONTROL request 🦋 A VERSION-CONTROL request does three distinct things:
- It creates a new "version history resource". In basic versioning, a version history resource isn't assigned a URL, so it isn't visible in the http scheme URL space 🙈 But when the version-history feature (see Section 5) is supported, that changes, and each version history resource gets its own new, distinct, and unique server-defined URL 🔥
- It creates a new "version resource" and adds it to the new version history resource. The body and dead properties of the new version resource are a copy of those of the versionable resource.
The server assigns the new version resource a new distinct and unique URL ✨
- It converts the versionable resource into a "version-controlled resource". The version-controlled resource keeps being identified by the same URL that identified it as a versionable resource 💅 As part of this conversion, it adds a
DAV:checked-inproperty, whose value contains the URL of the new version resource 👑
ngl, a versionable resource and a version-controlled resource aren't new types of resources 🌈 They don't introduce any new DAV:resourcetype. They're just any type of resource that supports the methods and live properties defined for them in this document, on top of all the methods and live properties implied by their DAV:resourcetype. So a collection (whose DAV:resourcetype is DAV:collection) is a versionable resource if it supports the VERSION-CONTROL method, and it's a version-controlled resource if it supports the version-controlled resource methods and live properties. It's giving layers 🧚
In the following example, foo.html is a versionable resource that gets put under version control 💜 After the VERSION-CONTROL request succeeds, there are two new resources: a new version history resource and a new version resource inside that version history. The versionable resource becomes a version-controlled resource, and its DAV:checked-in property points at the new version resource 🎀
The content and dead properties of a resource are represented by the symbol inside the box for that resource (for example, "S1" in the following example) 🍓
===VERSION-CONTROL==>
| +----+ version
| version- | | history
versionable | controlled +----+ resource
resource | resource |
/foo.html | /foo.html |
| v
+----+ | +----+ checked-in +----+ version
| S1 | | | S1 |----------->| S1 | resource
+----+ | +----+ +----+ /his/73/ver/1So before the VERSION-CONTROL request there was only one resource, and it wasn't under version control 🥹 After VERSION-CONTROL, there are three separate, distinct resources, each with its own state and properties: the version-controlled resource, the version resource, and the version history resource 🌸 Because the version-controlled resource and the version resource are separate resources, a method applied to the version-controlled resource only hits that version-controlled resource. It does NOT get applied to the version resource currently identified by that resource's DAV:checked-in property 🙅♀️ Even though the content and dead properties of a checked-in version-controlled resource are required to be the same as those of its current DAV:checked-in version, its live properties may differ 💀 A server can optimize storage by getting the content and dead properties of a checked-in version-controlled resource from its current DAV:checked-in version instead of storing them on the version-controlled resource. That's just an implementation optimization though, not a rule 🫶
Normally, a resource gets placed under version control with an explicit VERSION-CONTROL request ✨ A server MAY automatically place every new versionable resource under version control 🦋 In that case, the resulting state on the server MUST be the same as if the client had explicitly sent a VERSION-CONTROL request for that versionable resource 🔥 periodt 💅
2.2.2 Modifying a Version-Controlled Resource 💅
okay so if you want PUT or PROPPATCH to directly change the content or dead properties of a version-controlled resource, it has to be checked out first 🫶. When you check it back in, a brand new version gets made in that resource's version history ✨. The version you checked out gets remembered as the predecessor of that new version, iykyk 🦋.
The DAV:auto-version property (see Sections 3.2.2) of a checked-in version-controlled resource decides how it reacts when a method tries to modify its content or dead properties. Here are the possible reactions 🎀:
- Fail the request. The resource needs an explicit
CHECKOUTrequest before it can be modified (see Sections 4 and 9.2.1). 🙈 - Automatically checkout the resource, do the modification, and automatically checkin the resource. This means the server tracks every single state of the resource 👑, but it can lead to a seriously excessive number of versions being created 💀.
- Automatically checkout the resource, do the modification, and then, if the resource is not write-locked, automatically checkin the resource. If it IS write-locked, it stays checked-out until the write-lock goes away (either through a later
UNLOCKrequest or because the write-lock times out). This helps a locking client avoid a version pile-up, while still letting a non-locking client update the resource 🌸. - Automatically checkout the resource, do the modification, and then leave it checked out. If it's write-locked, it gets automatically checked in once the write-lock is removed, but a non-write-locked resource needs an explicit
CHECKINoperation (see Section 4.4). This keeps the number of new versions super low for a versioning unaware client 🍓, but only a versioning aware client can make new versions of a non-write-locked resource. - Fail the request unless the resource is write-locked. If it is write-locked, automatically checkout the resource and do the modification. The resource gets automatically checked in when the write-lock is removed. This keeps new versions to a minimum for a versioning unaware client 🧚, and it never automatically checks out a resource that won't later be automatically checked in.
The diagram below shows what checkout and checkin do to a version-controlled resource and its version history 🦋. The symbol inside a box (S1, S2, S3) is the current content and dead properties of the resource in that box. The symbol next to a box (V1, V2, V3) is the URL for that resource.
===checkout==> ===PUT==> ===checkin==>
/foo.html (version-controlled resource)
+----+ | +----+ | +----+ | +----+
| S2 | | | S2 | | | S3 | | | S3 |
+----+ | +----+ | +----+ | +----+
Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V3
/his/73 (version history for /foo.html)
+----+ | +----+ | +----+ | +----+
| S1 | V1 | | S1 | V1 | | S1 | V1 | | S1 | V1
+----+ | +----+ | +----+ | +----+
| | | | | | |
| | | | | | |
+----+ | +----+ | +----+ | +----+
| S2 | V2 | | S2 | V2 | | S2 | V2 | | S2 | V2
+----+ | +----+ | +----+ | +----+
| | | |
| | | |
| | | +----+
| | | | S3 | V3
| | | +----+Heads up: a version only captures a defined subset of a resource's state. For a basic resource, a version captures its content and dead properties, but NOT its live properties.
2.2.3 Reporting 📊
Sometimes getting versioning info about a resource means you have to pass parameters along with the request. Basic versioning includes required support for an extensible reporting mechanism ✨. That mechanism has a REPORT method, plus a live property that tells you which reports a particular resource supports. The REPORT method is required by versioning, but it can also be used in non-versioning WebDAV extensions 🦋.
If a client wants to query the properties of every version in the version history of a specified version-controlled resource, basic versioning gives it the DAV:version-tree report (see Section 3.7). An even more powerful version history reporting option is the DAV:expand-property report (see Section 3.8), applied to a version history resource (see Section 5) 💖.
3 Version-Control Feature 🎀
The version-control feature gives you support for putting a resource under version control. It creates an associated version-controlled resource and version history resource, as described in Section 2.2.1 🫶. A server says it supports the version-control feature by including the string "version-control" as a field in the DAV header of its response to an OPTIONS request. The version-control feature MUST be supported if any other versioning feature is supported 👑.
3.1 Additional Resource Properties ⭐
The version-control feature introduces the following REQUIRED properties for any WebDAV resource 🌈.
3.1.1 DAV:comment 💬
This property tracks a brief comment about a resource, one that's suitable to show a user. The DAV:comment of a version can be used to say why that version was created 🌸.
<!ELEMENT comment (#PCDATA)>
PCDATA value: string3.1.2 DAV:creator-displayname 🧑🎨
This property holds a description of the resource's creator that's suitable to show a user. The DAV:creator-displayname of a version can be used to say who created that version 🍓.
<!ELEMENT creator-displayname (#PCDATA)>
PCDATA value: string3.1.3 DAV:supported-method-set (protected) 🔒
This property identifies the methods that the resource supports. A method is supported by a resource if there is some state of that resource where applying that method will successfully satisfy all of that method's postconditions, including any extra postconditions added by the features the resource supports 🧚.
<!ELEMENT supported-method-set (supported-method*)>
<!ELEMENT supported-method ANY>
<!ATTLIST supported-method name NMTOKEN #REQUIRED>
name value: a method name3.1.4 DAV:supported-live-property-set (protected) 🦋
This property identifies the live properties the resource supports. A live property is supported by a resource if the resource has the semantics defined for that property ✨. The value of this property MUST identify all live properties defined by this document that the resource supports, and it SHOULD also identify all live properties the resource supports 💅.
<!ELEMENT supported-live-property-set (supported-live-property*)>
<!ELEMENT supported-live-property name>
<!ELEMENT prop ANY>
ANY value: a property element type3.1.5 DAV:supported-report-set (protected) 📋
This property identifies the reports the resource supports 🫧.
<!ELEMENT supported-report-set (supported-report*)>
<!ELEMENT supported-report report>
<!ELEMENT report ANY>
ANY value: a report element type3.2 Version-Controlled Resource Properties 🎀
The version-control feature introduces the following REQUIRED properties for a version-controlled resource 💖.
3.2.1 DAV:checked-in (protected) ✅
This property shows up on a checked-in version-controlled resource and identifies a version with the same content and dead properties as that resource. It gets removed when the resource is checked out, then added back (now pointing at a new version) when the resource is checked back in 🔄.
<!ELEMENT checked-in (href)>3.2.2 DAV:auto-version 🪄
If the DAV:auto-version value is DAV:checkout-checkin, then when a modification request (such as PUT/PROPPATCH) is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout and followed by a checkin operation 🔁.
If the DAV:auto-version value is DAV:checkout-unlocked-checkin, then when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation. If the resource is not write-locked, the request is automatically followed by a checkin operation 🌷.
If the DAV:auto-version value is DAV:checkout, then when a modification request is applied to a checked-in version-controlled resource, the request is automatically preceded by a checkout operation 🍭.
If the DAV:auto-version value is DAV:locked-checkout, then when a modification request is applied to a write-locked checked-in version-controlled resource, the request is automatically preceded by a checkout operation 🔐.
If an update to a write-locked checked-in resource is automatically preceded by a checkout of that resource, the checkout is associated with the write lock. When that write lock is removed (for example, from an UNLOCK or a lock timeout), if the resource hasn't been checked in yet, the write lock's removal is automatically preceded by a checkin operation 🫶.
A server MAY refuse to let the DAV:auto-version property be modified, or it MAY only support values from a subset of the valid values 🙃.
<!ELEMENT auto-version (checkout-checkin | checkout-unlocked-checkin
| checkout | locked-checkout)? >
<!ELEMENT checkout-checkin EMPTY>
<!ELEMENT checkout-unlocked-checkin EMPTY>
<!ELEMENT checkout EMPTY>
<!ELEMENT locked-checkout EMPTY>3.3 Checked-Out Resource Properties 📝
The version-control feature introduces the following REQUIRED properties for a checked-out resource 💜.
3.3.1 DAV:checked-out (protected) 📌
This property identifies the version that the DAV:checked-in property pointed to when the resource was checked out. It gets removed when the resource is checked in 🌟.
<!ELEMENT checked-out (href)>3.3.2 DAV:predecessor-set 🌿
This property determines the DAV:predecessor-set property of the version that results from checking in this resource 🦄.
A server MAY reject attempts to modify the DAV:predecessor-set of a version-controlled resource 🚫.
<!ELEMENT predecessor-set (href+)>3.4 Version Properties 🌈
The version-control feature introduces the following REQUIRED properties for a version 💫.
3.4.1 DAV:predecessor-set (protected) ⬅️
This property identifies each predecessor of this version. Except for the root version, which has no predecessors, every version has at least one predecessor 🌳.
<!ELEMENT predecessor-set (href*)>3.4.2 DAV:successor-set (computed) ➡️
This property identifies each version whose DAV:predecessor-set identifies this version 🔮.
<!ELEMENT successor-set (href*)>3.4.3 DAV:checkout-set (computed) 🛎️
This property identifies each checked-out resource whose DAV:checked-out property identifies this version 🎀.
<!ELEMENT checkout-set (href*)>3.4.4 DAV:version-name (protected) 💖
okay so this property holds a server-made string for each version in a version history 🎀 every version gets its own, and it's meant to be shown to a human. The version's URL is for clients, so users usually never see it 👀
<!ELEMENT version-name (#PCDATA)>
PCDATA value: string3.5 VERSION-CONTROL Method 🦋
bestie, a VERSION-CONTROL request is how you put a resource under version control at the request-URL 🫶 it works on a versionable resource or on one that's already version-controlled.
If the request-URL is a versionable resource, the server makes a brand new version history, makes a new version with copies of the content and dead properties, and gives the resource a DAV:checked-in property pointing at that new version 🍓
If the request-URL is already version-controlled, it just stays that way. This means a client doesn't have to care whether the server auto-versions new resources or not ✨
If a VERSION-CONTROL request fails, the server state from before the request MUST be restored. 😭
Marshalling:
If a request body is included, it MUST be a DAV:version-control XML element.
<!ELEMENT version-control ANY>If a response body for a successful request is included, it MUST be a DAV:version-control-response XML element. This doc doesn't define any elements for the VERSION-CONTROL response body, but DAV:version-control-response is there so future extensions that DO define those elements still work together nicely 🧚
<!ELEMENT version-control-response ANY>Postconditions:
(DAV:put-under-version-control): If the request-URL was a versionable resource at the time of the request, the request MUST have created a new version history and MUST have created a new version resource in it. The resource MUST have a DAV:checked-in property that identifies the new version. The content, dead properties, and DAV:resourcetype of the new version MUST be the same as those of the resource. Also, the implementation can put the version history and version resources basically anywhere it wants 🌈 same host and server as the version-controlled resource, a different virtual host on the same server, the same host run by a different server, or a different host run by a different server. Iconic flexibility 💅
(DAV:must-not-change-existing-checked-in-out): If the request-URL was already under version control at the time of the request, the request MUST NOT change that resource's DAV:checked-in or DAV:checked-out property. Hands off, no cap 🙈
3.5.1 Example - VERSION-CONTROL 🌸
>>REQUEST
VERSION-CONTROL /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OKIn this example, /foo.html gets put under version control. A new version history is made for it, and a new version is created with a copy of /foo.html's content and dead properties. The DAV:checked-in property of /foo.html points at that new version. Main character energy ✨
3.6 REPORT Method 🧚
okay so a REPORT request is an extensible way to get information about a resource. A normal property has one single value, but a report can change depending on extra info in the REPORT request body and headers 😭
Marshalling:
The body of a REPORT request says which report you're asking for, plus any extra details used to customize it.
The request MAY include a Depth header. If no Depth header is included, Depth:0 is assumed.
The response body for a successful request MUST contain the requested report.
If a Depth request header is included, the response MUST be a 207 Multi-Status. The request MUST be applied separately to the collection itself and to all members of the collection that satisfy the Depth value. The DAV:prop element of a DAV:response for a given resource MUST contain the requested report for that resource. Separate but equal 💖
Preconditions:
(DAV:supported-report): The specified report MUST be supported by the resource identified by the request-URL.
Postconditions:
(DAV:no-modification): The REPORT method MUST NOT have changed the content or dead properties of any resource. Look but don't touch 👀
3.7 DAV:version-tree Report 🍓
the DAV:version-tree report describes the requested properties of all the versions in the version history of a version. If you request it for a version-controlled resource, it gets redirected to that resource's DAV:checked-in or DAV:checked-out version 🦋
The DAV:version-tree report MUST be supported by all version resources and all version-controlled resources. Non-negotiable 🔥
Marshalling:
The request body MUST be a DAV:version-tree XML element.
<!ELEMENT version-tree ANY>
ANY value: a sequence of zero or more elements, with at most one
DAV:prop element.
prop: see RFC 2518, Section 12.11The response body for a successful request MUST be a DAV:multistatus XML element.
multistatus: see RFC 2518, Section 12.9
The response body for a successful DAV:version-tree REPORT request MUST contain a DAV:response element for each version in the version history of the version identified by the request-URL. Every single one, bestie 🫶
3.7.1 Example - DAV:version-tree Report 🎀
The version history drawn below would produce the following version tree report. Picture it:
foo.html History
+---+
| | V1
+---+
/ \
/ \
+---+ +---+
| | V2 | | V2.1.1
+---+ +---+>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-tree xmlns:D="DAV:">
<D:prop>
<D:version-name/>
<D:creator-displayname/>
<D:successor-set/>
</D:prop>
</D:version-tree>
>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
<D:propstat>
<D:prop>
<D:version-name>V1</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
<D:successor-set>
<D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
<D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
</D:successor-set>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
<D:propstat>
<D:prop>
<D:version-name>V2</D:version-name>
<D:creator-displayname>Fred</D:creator-displayname>
<D:successor-set/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
<D:propstat>
<D:prop>
<D:version-name>V2.1.1</D:version-name>
<D:creator-displayname>Sally</D:creator-displayname>
<D:successor-set/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>3.8 DAV:expand-property Report 🌈
okay so lots of property values are defined as a DAV:href, or a set of DAV:href elements. The DAV:expand-property report lets you grab the properties of all the resources those DAV:href elements point to in one single request 🫶 that means fewer requests overall, and the server can also cut down on how many separate read transactions it needs on the underlying versioning store. Efficiency is so hot right now 🔥
The DAV:expand-property report SHOULD be supported by all resources that support the REPORT method. Honestly everyone should be on this 💅
Marshalling:
The request body MUST be a DAV:expand-property XML element.
<!ELEMENT expand-property (property*)>
<!ELEMENT property (property*)>
<!ATTLIST property name NMTOKEN #REQUIRED>
name value: a property element type
<!ATTLIST property namespace NMTOKEN "DAV:">
namespace value: an XML namespaceThe response body for a successful request MUST be a DAV:multistatus XML element.
multistatus: see RFC 2518, Section 12.9
The properties reported in the DAV:prop elements of the DAV:multistatus element MUST be those identified by the DAV:property elements in the DAV:expand-property element. If there are DAV:property elements nested within a DAV:property element, then every DAV:href in the value of the corresponding property is replaced by a DAV:response element whose DAV:prop elements report the values of the properties identified by the nested DAV:property elements. The nested DAV:property elements can in turn contain DAV:property elements, so you can ask for multiple levels of DAV:href expansion. Layers on layers 🎀
Note that a validating parser MUST be aware that the DAV:expand-property report effectively modifies the DTD of every property by replacing every occurrence of "href" in the DTD with "href | response". This one's a plot twist, so be ready 😭
3.8.1. Example - DAV:expand-property ✨
okay bestie, this example is literally about asking a versioned resource for the DAV:creator-displayname and DAV:activity-set of every version in its version history 🦋. It assumes the server supports the version-history feature (see Section 5) 💅.
>>REQUEST
REPORT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:expand-property xmlns:D="DAV:">
<D:property name="version-history">
<D:property name="version-set">
<D:property name="creator-displayname"/>
<D:property name="activity-set"/>
</D:property>
</D:property>
</D:expand-property>>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/foo.html</D:href>
<D:propstat>
<D:prop>
<D:version-history>
<D:response>
<D:href>http://repo.webdav.org/his/23</D:href>
<D:propstat>
<D:prop>
<D:version-set>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/1</D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Fred</D:creator-displayname>
<D:activity-set> <D:href>
http://www.webdav.org/ws/dev/sally
</D:href> </D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
<D:response>
<D:href>http://repo.webdav.org/his/23/ver/2</D:href>
<D:propstat>
<D:prop>
<D:creator-displayname>Sally</D:creator-displayname>
<D:activity-set>
<D:href>http://repo.webdav.org/act/add-refresh-cmd</D:href>
</D:activity-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-set> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:version-history> </D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat> </D:response>
</D:multistatus>In this example, the DAV:creator-displayname and DAV:activity-set properties of the versions in the DAV:version-set of the DAV:version-history of http://www.webdav.org/foo.html are reported. The server basically hands back the whole gossip file in one go 🫶🌸
3.9. Additional OPTIONS Semantics 🎀
okay so if the server supports the version-control feature, it MUST include "version-control" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods 🧚. no exceptions, periodt 💅
3.10. Additional PUT Semantics 💖
Additional Preconditions:
(DAV:cannot-modify-version-controlled-content): If the request-URL identifies a resource with aDAV:checked-inproperty, the request MUST fail unlessDAV:auto-versionsemantics will automatically check out the resource. 🙈(DAV:cannot-modify-version): If the request-URL identifies a version, the request MUST fail. no touching the past, bestie 🕰️
If the request creates a new resource that is automatically placed under version control, all preconditions for VERSION-CONTROL apply to the request ✨
Additional Postconditions:
(DAV:auto-checkout): If the resource was a checked-in version-controlled resource whoseDAV:auto-versionproperty indicates it should be automatically checked out but not automatically checked in for a modification request, then the server MUST have automatically checked out the resource prior to executing the request. In particular, the value of theDAV:checked-outproperty of the resource MUST be that of theDAV:checked-inproperty prior to the request, theDAV:checked-inproperty MUST have been removed, and theDAV:predecessor-setproperty MUST be initialized to be the same as theDAV:checked-outproperty. If any part of the checkout/update sequence failed, the status from the failed part of the request MUST be returned, and the server state preceding the request sequence MUST be restored. the whole thing rewinds if it flops 🔁(DAV:auto-checkout-checkin): If the resource was a checked-in version-controlled resource whoseDAV:auto-versionproperty indicates it should be automatically checked out and automatically checked in for a modification request, then the server MUST have automatically checked out the resource prior to executing the request and automatically checked it in after the request. In particular, theDAV:checked-inproperty of the resource MUST identify a new version whose content and dead properties are the same as those of the resource. TheDAV:predecessor-setof the new version MUST identify the version identified by theDAV:checked-inproperty prior to the request. If any part of the checkout/update/checkin sequence failed, the status from the failed part of the request MUST be returned, and the server state preceding the request sequence MUST be restored. same rewind energy, but with a brand new version in the mix 🦋
If the request creates a new resource, the new resource MAY have automatically been placed under version control, and all postconditions for VERSION-CONTROL apply to the request 🌈
3.11. Additional PROPFIND Semantics 🍓
A DAV:allprop PROPFIND request SHOULD NOT return any of the properties defined by this document. this lets a versioning server stay fast when a naive client, which doesn't understand the cost of asking a server to compute all possible live properties, sends a DAV:allprop PROPFIND request. the server is protecting itself, and honestly that's iconic 👑
Additional Preconditions:
(DAV:supported-live-property): If the request attempts to access a property defined by this document, the semantics of that property MUST be supported by the server. 🔥
3.12. Additional PROPPATCH Semantics 🌸
Additional Preconditions:
(DAV:cannot-modify-version-controlled-property): If the request attempts to modify a dead property, same semantics as PUT (see Section 3.10). 💅(DAV:cannot-modify-version): If the request attempts to modify a dead property, same semantics as PUT (see Section 3.10). no sneaking into old versions 🙈(DAV:cannot-modify-protected-property): An attempt to modify a property that is defined by this document, as being protected for that kind of resource, MUST fail. protected means protected, bestie 🔒(DAV:supported-live-property): An attempt to modify a property defined by this document, but whose semantics are not enforced by the server, MUST fail. This helps ensure that a client will be notified when it is trying to use a property whose semantics are not supported by the server. so the client finds out early instead of getting ghosted later 👻
Additional Postconditions:
(DAV:auto-checkout): If the request modified a dead property, same semantics as PUT (see Section 3.10). ✨(DAV:auto-checkout-checkin): If the request modified a dead property, same semantics as PUT (see Section 3.10). 🫶
3.13. Additional DELETE Semantics 🧚
Additional Preconditions:
(DAV:no-version-delete): A server MAY fail an attempt to DELETE a version. it's allowed to say no here, so no drama if it does 💀
Additional Postconditions:
(DAV:update-predecessor-set): If a version was deleted, the server MUST have replaced any reference to that version in aDAV:predecessor-setby a copy of theDAV:predecessor-setof the deleted version. the deleted version's history gets passed down so nothing gets orphaned 🦋
3.14. Additional COPY Semantics 💜
Additional Preconditions:
If the request creates a new resource that is automatically placed under version control, all preconditions for VERSION-CONTROL apply to the request ✨
Additional Postconditions:
(DAV:must-not-copy-versioning-property): A property defined by this document MUST NOT have been copied to the new resource created by this request, but instead that property of the new resource MUST have the default initial value it would have had if the new resource had been created by a non-versioning method such as PUT or a MKCOL. versioning props don't get copy-pasted, they start fresh 🍓(DAV:auto-checkout): If the destination is a version-controlled resource, same semantics as PUT (see Section 3.10). 🌈(DAV:auto-checkout-checkin): If the destination is a version-controlled resource, same semantics as PUT (see Section 3.10). 💖(DAV:copy-creates-new-resource): If the source of a COPY is a version-controlled resource or version, and if there is no resource at the destination of the COPY, then the COPY creates a new non-version-controlled resource at the destination of the COPY. The new resource MAY automatically be put under version control, but the resulting version-controlled resource MUST be associated with a new version history created for that new version-controlled resource, and all postconditions forVERSION-CONTROLapply to the request. a fresh copy gets its own brand new history, main character energy 👑
3.15. Additional MOVE Semantics 🎀
Additional Preconditions:
(DAV:cannot-rename-version): If the request-URL identifies a version, the request MUST fail. versions don't get renamed, full stop 🚫
Additional Postconditions:
(DAV:preserve-versioning-properties): When a resource is moved from a source URL to a destination URL, a property defined by this document MUST have the same value at the destination URL as it had at the source URL. the versioning props travel with the resource, no changes 🧳
3.16. Additional UNLOCK Semantics 🔓
Note that these semantics apply both to an explicit UNLOCK request, as well as to the removal of a lock because of a lock timeout. If a precondition or postcondition cannot be satisfied, the lock timeout MUST NOT occur. no half-finished lock timeouts, that's a hard no 🙅♀️
Additional Preconditions:
(DAV:version-history-is-tree): If the request-URL identifies a checked-out version-controlled resource that will be automatically checked in when the lock is removed, then the versions identified by theDAV:predecessor-setof the checked-out resource MUST be descendants of the root version of the version history for theDAV:checked-outversion. the whole history has to stay a tree, the family tree has to make sense 🌳
Additional Postconditions:
(DAV:auto-checkin): If the request-URL identified a checked-out version-controlled resource that had been automatically checked out because of itsDAV:auto-versionproperty, the request MUST have created a new version in the version history of theDAV:checked-outversion. The request MUST have allocated a URL for the version that MUST NOT have previously identified any other resource, and MUST NOT ever identify a resource other than this version. The content, dead properties,DAV:resourcetype, andDAV:predecessor-setof the new version MUST be copied from the checked-out resource. TheDAV:version-nameof the new version MUST be set to a server-defined value distinct from all otherDAV:version-namevalues of other versions in the same version history. The request MUST have removed theDAV:checked-outproperty of the version-controlled resource, and MUST have added aDAV:checked-inproperty that identifies the new version. auto-checkin is the big finale, and the new version gets its own unique URL and name, so iconic ⭐🌈
4. CHECKOUT-IN-PLACE FEATURE ✨
okay so with the version-control feature, WebDAV locking can be used to stop a version explosion 💥 that would happen if every single edit made a brand new version 😭. The checkout-in-place feature is the alternative 🦋. It lets a client explicitly check out and check in a resource to create a new version, and that's it. Iconic, honestly 💅.
4.1. Additional Version Properties
Okay so the checkout-in-place feature brings along some REQUIRED properties for a version 👑.
4.1.1. DAV:checkout-fork
This one controls what CHECKOUT does when a version is already checked out or already has a successor 🫶. If the DAV:checkout-fork of a version is DAV:forbidden, a CHECKOUT request MUST fail if it would result in that version showing up in the DAV:predecessor-set or DAV:checked-out property of more than one version or checked-out resource. If DAV:checkout-fork is DAV:discouraged, such a CHECKOUT request MUST fail unless DAV:fork-ok is specified in the CHECKOUT request body.
A server MAY reject attempts to modify the DAV:checkout-fork of a version. 🙈
<!ELEMENT checkout-fork ANY>
ANY value: A sequence of elements with at most one DAV:discouraged
or DAV:forbidden element.
<!ELEMENT discouraged EMPTY>
<!ELEMENT forbidden EMPTY>4.1.2. DAV:checkin-fork
This one controls what happens to CHECKIN when a version already has a successor 🦋. If the DAV:checkin-fork of a version is DAV:forbidden, a CHECKIN request MUST fail if it would result in that version appearing in the DAV:predecessor-set of more than one version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN request MUST fail unless DAV:fork-ok is specified in the CHECKIN request body.
A server MAY reject attempts to modify the DAV:checkout-fork of a version. 💀
<!ELEMENT checkin-fork ANY>
ANY value: A sequence of elements with at most one DAV:discouraged
or DAV:forbidden element.
<!ELEMENT discouraged EMPTY>
<!ELEMENT forbidden EMPTY>4.2. Checked-Out Resource Properties
The checkout-in-place feature also introduces some REQUIRED properties for a checked-out resource 🌸.
4.2.1. DAV:checkout-fork
This property decides the DAV:checkout-fork property of the version that comes out of checking in this resource 🎀.
4.2.2. DAV:checkin-fork
This property decides the DAV:checkin-fork property of the version that comes out of checking in this resource ✨.
4.3. CHECKOUT Method (applied to a version-controlled resource)
A CHECKOUT request can be applied to a checked-in version-controlled resource so you can change its content and dead properties 🍓.
If a CHECKOUT request fails, the server state preceding the request MUST be restored. Bestie, that's a must-have 💅.
Marshalling:
If a request body is included, it MUST be a DAV:checkout XML element.
<!ELEMENT checkout ANY>
ANY value: A sequence of elements with at most one DAV:fork-ok
element.
<!ELEMENT fork-ok EMPTY>If a response body for a successful request is included, it MUST be a DAV:checkout-response XML element.
<!ELEMENT checkout-response ANY>The response MUST include a Cache-Control:no-cache header. 🧊
Preconditions:
- (DAV:must-be-checked-in): If a version-controlled resource is being checked out, it MUST have a
DAV:checked-inproperty. - (DAV:checkout-of-version-with-descendant-is-forbidden): If the
DAV:checkout-forkproperty of the version being checked out isDAV:forbidden, the request MUST fail if a version identifies that version in itsDAV:predecessor-set. - (DAV:checkout-of-version-with-descendant-is-discouraged): If the
DAV:checkout-forkproperty of the version being checked out isDAV:discouraged, the request MUST fail if a version identifies that version in itsDAV:predecessor-setunlessDAV:fork-okis specified in the request body. - (DAV:checkout-of-checked-out-version-is-forbidden): If the
DAV:checkout-forkproperty of the version being checked out isDAV:forbidden, the request MUST fail if a checked-out resource identifies that version in itsDAV:checked-outproperty. - (DAV:checkout-of-checked-out-version-is-discouraged): If the
DAV:checkout-forkproperty of the version being checked out isDAV:discouraged, the request MUST fail if a checked-out resource identifies that version in itsDAV:checked-outproperty unlessDAV:fork-okis specified in the request body.
Postconditions:
- (DAV:is-checked-out): The checked-out resource MUST have a
DAV:checked-outproperty that identifies theDAV:checked-inversion preceding the checkout. The version-controlled resource MUST NOT have aDAV:checked-inproperty. - (DAV:initialize-predecessor-set): The
DAV:predecessor-setproperty of the checked-out resource MUST be initialized to be theDAV:checked-outversion.
4.3.1. Example - CHECKOUT of a version-controlled resource
>>REQUEST
CHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cacheIn this example, the version-controlled resource /foo.html is checked out 🌈.
4.4. CHECKIN Method (applied to a version-controlled resource)
A CHECKIN request can be applied to a checked-out version-controlled resource to make a new version 🎀. That new version gets its content and dead properties copied over from the checked-out resource, so it's giving continuity 🦋.
If a CHECKIN request fails, the server state preceding the request MUST be restored. 😭
Marshalling:
If a request body is included, it MUST be a DAV:checkin XML element.
<!ELEMENT checkin ANY>
ANY value: A sequence of elements with at most one
DAV:keep-checked-out element and at most one DAV:fork-ok element.
<!ELEMENT keep-checked-out EMPTY>
<!ELEMENT fork-ok EMPTY>If a response body for a successful request is included, it MUST be a DAV:checkin-response XML element.
<!ELEMENT checkin-response ANY>The response MUST include a Cache-Control:no-cache header. 🧊
Preconditions:
- (DAV:must-be-checked-out): The request-URL MUST identify a resource with a
DAV:checked-outproperty. - (DAV:version-history-is-tree) The versions identified by the
DAV:predecessor-setof the checked-out resource MUST be descendants of the root version of the version history for theDAV:checked-outversion. - (DAV:checkin-fork-forbidden): A
CHECKINrequest MUST fail if it would cause a version whoseDAV:checkin-forkisDAV:forbiddento appear in theDAV:predecessor-setof more than one version. - (DAV:checkin-fork-discouraged): A
CHECKINrequest MUST fail if it would cause a version whoseDAV:checkin-forkisDAV:discouragedto appear in theDAV:predecessor-setof more than one version, unlessDAV:fork-okis specified in the request body.
Postconditions:
- (DAV:create-version): The request MUST have created a new version in the version history of the
DAV:checked-outversion. The request MUST have allocated a distinct new URL for the new version, and that URL MUST NOT ever identify any resource other than that version. The URL for the new version MUST be returned in aLocationresponse header. - (DAV:initialize-version-content-and-properties): The content, dead properties,
DAV:resourcetype, andDAV:predecessor-setof the new version MUST be copied from the checked-out resource. TheDAV:version-nameof the new version MUST be set to a server-defined value distinct from all otherDAV:version-namevalues of other versions in the same version history. - (DAV:checked-in): If the request-URL identifies a version-controlled resource and
DAV:keep-checked-outis not specified in the request body, theDAV:checked-outproperty of the version-controlled resource MUST have been removed and aDAV:checked-inproperty that identifies the new version MUST have been added. - (DAV:keep-checked-out): If
DAV:keep-checked-outis specified in the request body, theDAV:checked-outproperty of the checked-out resource MUST have been updated to identify the new version.
4.4.1. Example - CHECKIN
>>REQUEST
CHECKIN /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/his/23/ver/32
Cache-Control: no-cacheIn this example, version-controlled resource /foo.html is checked in, and a new version is created at http://repo.webdav.org/his/23/ver/32 🥹.
4.5. UNCHECKOUT Method
An UNCHECKOUT request can be applied to a checked-out version-controlled resource to cancel the CHECKOUT and bring back the pre-CHECKOUT state 🫧.
If an UNCHECKOUT request fails, the server MUST undo any partial effects of the UNCHECKOUT request. 🔁
Marshalling:
If a request body is included, it MUST be a DAV:uncheckout XML element.
<!ELEMENT uncheckout ANY>If a response body for a successful request is included, it MUST be a DAV:uncheckout-response XML element.
<!ELEMENT uncheckout-response ANY>The response MUST include a Cache-Control:no-cache header. 🧊
Preconditions:
- (DAV:must-be-checked-out-version-controlled-resource): The request-URL MUST identify a version-controlled resource with a
DAV:checked-outproperty.
Postconditions:
- (DAV:cancel-checked-out): The value of the
DAV:checked-inproperty is that of theDAV:checked-outproperty prior to the request, and theDAV:checked-outproperty has been removed. - (DAV:restore-content-and-dead-properties): The content and dead properties of the version-controlled resource are copies of its
DAV:checked-inversion.
4.5.1. Example - UNCHECKOUT
>>REQUEST
UNCHECKOUT /foo.html HTTP/1.1
Host: www.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cacheIn this example, the content and dead properties of the version-controlled resource identified by http://www.webdav.org/foo.html are restored to what they were before the most recent CHECKOUT of that resource 🪄.
4.6. Additional OPTIONS Semantics
If a server supports the checkout-in-place feature, it MUST include "checkout-in-place" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods 📣.
5. Version-History Feature
Okay, so it's super useful to still have access to a version history after every version-controlled resource in it has been deleted 🕰️. A server can make that happen by supporting version history resources. A version history resource lives in a server-defined namespace, so it isn't affected by any deletion or movement of version-controlled resources 🧚. It's the perfect spot for a property that logically applies to all states of a resource 💜. The DAV:expand-property report (see Section 3.8) can be applied to the DAV:version-set of a version history resource to get a bunch of useful reports on all the versions in that version history 📊.
5.1. Version History Properties
The DAV:resourcetype of a version history MUST be DAV:version-history. 👑
The version-history feature introduces the following REQUIRED properties for a version history. ✨
5.1.1. DAV:version-set (protected)
This property identifies each version of this version history 🌷.
<!ELEMENT version-set (href+)>5.1.2 DAV:root-version (computed) 🌳
okay so this one tells you which version is the root version of this version history 🌸
<!ELEMENT root-version (href)>5.2 Additional Version-Controlled Resource Properties 💅
the version-history feature introduces the following REQUIRED property for a version-controlled resource, and honestly it's giving main character energy 🎀
5.2.1 DAV:version-history (computed) 🦋
this property identifies the version history resource for the DAV:checked-in or DAV:checked-out version of this version-controlled resource ✨
<!ELEMENT version-history (href)>5.3 Additional Version Properties 🧚
the version-history feature also introduces the following REQUIRED property for a version 💜
5.3.1 DAV:version-history (computed) 🍓
this property identifies the version history that contains this version 🫶
<!ELEMENT version-history (href)>5.4 DAV:locate-by-history Report 🔥
bestie, so many properties point to a version from some version history 🙈 it's often super useful to be able to efficiently find a version-controlled resource for that version history. the DAV:locate-by-history report can be applied to a collection to locate the collection member that is a version-controlled resource for a specified version history resource 💖
Marshalling:
- The request body MUST be a DAV:locate-by-history XML element.
<!ELEMENT locate-by-history (version-history-set, prop)>
<!ELEMENT version-history-set (href+)>
prop: see RFC 2518, Section 12.11- The response body for a successful request MUST be a DAV:multistatus XML element containing every version-controlled resource that is a member of the collection identified by the request-URL, and whose DAV:version-history property identifies one of the version history resources identified by the request body. The DAV:prop element in the request body identifies which properties should be reported in the DAV:prop elements in the response body ✨
Preconditions:
- (DAV:must-be-version-history): Each member of the DAV:version-history-set element in the request body MUST identify a version history resource. 🌈
5.4.1 Example - DAV:locate-by-history Report 🧁
REQUEST
REPORT /ws/public HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:locate-by-history xmlns:D="DAV:">
<D:version-history-set>
<D:href>http://repo.webdav.org/his/23</D:href>
<D:href>http://repo.webdav.org/his/84</D:href>
<D:href>http://repo.webdav.org/his/129</D:href>
<D:version-history-set/>
<D:prop>
</D:version-history>
</D:prop>
</D:locate-by-history>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/ws/public/x/test.html</D:href>
<D:propstat>
<D:prop>
<D:version-history>
<D:href>http://repo.webdav.org/his/23</D:href>
</D:version-history>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>in this example, there is only one version-controlled member of /ws/public that is a version-controlled resource for one of the three specified version history resources. specifically, /ws/public/x/test.html is the version-controlled resource for http://repo.webdav.org/his/23 🦋
5.5 Additional OPTIONS Semantics ✨
if the server supports the version-history feature, it MUST include "version-history" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods 🫶
a DAV:version-history-collection-set element MAY be included in the request body to identify collections that may contain version history resources 💜
Additional Marshalling:
- If an XML request body is included, it MUST be a DAV:options XML element.
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one
DAV:version-history-collection-set element.- If an XML response body for a successful request is included, it MUST be a DAV:options-response XML element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one
DAV:version-history-collection-set element.
<!ELEMENT version-history-collection-set (href*)>- If DAV:version-history-collection-set is included in the request body, the response body for a successful request MUST contain a DAV:version-history-collection-set element identifying collections that may contain version histories. An identified collection MAY be the root collection of a tree of collections, all of which may contain version histories. Since different servers can control different parts of the URL namespace, different resources on the same host MAY have different DAV:version-history-collection-set values. The identified collections MAY be located on different hosts from the resource 🌸
5.6 Additional DELETE Semantics 🔥
Additional Postconditions:
- (DAV:delete-version-set): If the request deleted a version history, the request MUST have deleted all versions in the DAV:version-set of that version history, and MUST have satisfied the postconditions for version deletion (see Section 3.13). 💀
- (DAV:version-history-has-root): If the request deleted the root version of a version history, the request MUST have updated the DAV:root-version of the version history to refer to another version that is an ancestor of all other remaining versions in that version history. A result of this postcondition is that every version history will have at least one version, and the only way to delete all versions is to delete the version history resource. 😭
5.7 Additional COPY Semantics 🧚
Additional Preconditions:
- (DAV:cannot-copy-history): If the request-URL identifies a version history, the request MUST fail. In order to create another version history whose versions have the same content and dead properties, the appropriate sequence of VERSION-CONTROL, CHECKOUT, PUT, PROPPATCH, and CHECKIN requests must be made. 🙅♀️
5.8 Additional MOVE Semantics 🎀
Additional Preconditions:
- (DAV:cannot-rename-history): If the request-URL identifies a version history, the request MUST fail. 💅
5.9 Additional VERSION-CONTROL Semantics 🌈
Additional Postconditions:
- (DAV:new-version-history): If the request created a new version history, the request MUST have allocated a new server-defined URL for that version history that MUST NOT have previously identified any other resource, and MUST NOT ever identify a resource other than this version history 🔒
5.10 Additional CHECKIN Semantics ⭐
Additional Postconditions:
- (DAV:add-to-history): A URL for the new version resource MUST have been added to the DAV:version-set of the version history of the DAV:checked-out version 🫶
6. Workspace Feature ✨
in order to allow multiple users to work concurrently on adding versions to the same version history, it is necessary to allocate on the server multiple checked-out resources for the same version history. even if only one user is making changes to a resource, that user will sometimes wish to create a "private" version, and then to expose that version at a later time 🤫 one way to provide this functionality depends on the client keeping track of its current set of checked-out resources. this is the working-resource feature defined in Section 8. the other way avoids the need for persistent state on the client, and instead has the server maintain a human meaningful namespace for related sets of checked-out resources. this is the workspace feature defined in this section 🧚
the workspace feature introduces a "workspace resource". a workspace resource is a collection whose members are related version-controlled and non-version-controlled resources. multiple workspaces may be used to expose different versions and configurations of a set of version-controlled resources concurrently. in order to make changes to a version-controlled resource in one workspace visible in another workspace, that version-controlled resource must be checked in, and then the corresponding version-controlled resource in the other workspace can be updated to display the content and dead properties of the new version 🌸
in order to ensure unambiguous merging (see Section 11) and baselining (see Section 12) semantics, a workspace may contain at most one version-controlled resource for a given version history. this is required for unambiguous merging because the MERGE method must identify which version-controlled resource is to be the merge target of a given version. this is required for unambiguous baselining because a baseline can only select one version for a given version-controlled resource 🍓
initially, an empty workspace can be created. non-version-controlled resources can then be added to the workspace with standard WebDAV requests such as PUT and MKCOL. version-controlled resources can be added to the workspace with VERSION-CONTROL requests. if the baseline feature is supported, collections in the workspace can be placed under baseline control, and then initialized by existing baselines 🎀
6.1 Workspace Properties 💜
the workspace feature introduces the following REQUIRED property for a workspace 🫶
6.1.1 DAV:workspace-checkout-set (computed) 🦋
this property identifies each checked-out resource whose DAV:workspace property identifies this workspace ✨
<!ELEMENT workspace-checkout-set (href*)>6.2 Additional Resource Properties 🌈
the workspace feature introduces the following REQUIRED property for a WebDAV resource 💅
6.2.1 DAV:workspace (protected) 🔒
the DAV:workspace property of a workspace resource MUST identify itself. the DAV:workspace property of any other type of resource MUST be the same as the DAV:workspace of its parent collection 🧁
<!ELEMENT workspace (href)>6.3 MKWORKSPACE Method 🔥
a MKWORKSPACE request creates a new workspace resource. a server MAY restrict workspace creation to particular collections, but a client can determine the location of these collections from a DAV:workspace-collection-set OPTIONS request (see Section 6.4) 🧚
if a MKWORKSPACE request fails, the server state preceding the request MUST be restored 😭
Marshalling:
- If a request body is included, it MUST be a DAV:mkworkspace XML element.
<!ELEMENT mkworkspace ANY>- If a response body for a successful request is included, it MUST be a DAV:mkworkspace-response XML element.
<!ELEMENT mkworkspace-response ANY>- The response MUST include a Cache-Control:no-cache header. 🌸
Preconditions:
- (DAV:resource-must-be-null): A resource MUST NOT exist at the request-URL.
- (DAV:workspace-location-ok): The request-URL MUST identify a location where a workspace can be created. 🍓
Postconditions:
- (DAV:initialize-workspace): A new workspace exists at the request-URL. The DAV:resourcetype of the workspace MUST be DAV:collection. The DAV:workspace of the workspace MUST identify the workspace. 🌈
6.3.1 Example - MKWORKSPACE 🧚
REQUEST
MKWORKSPACE /ws/public HTTP/1.1
Host: www.webdav.org
Content-Length: 0RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cacheokay so here we're making a brand new workspace at http://www.webdav.org/ws/public 🎀 the server says 201 Created and we're literally done, bestie 💅
6.4 Additional OPTIONS Semantics 🌸
okay this part is giving "if you support workspaces, you've gotta say so" 🫶 if a server supports the workspace feature, it MUST include "workspace" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods.
and no skipping stuff, babe ✨ if a server supports the workspace feature, it MUST also support the checkout-in-place feature and the version-history feature.
a DAV:workspace-collection-set element MAY be included in the request body to point at the collections that may hold workspace resources 🦋
Additional Marshalling:
the XML rules are lowkey strict, so here's the exact shape 🎀
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one
DAV:workspace-collection-set element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one
DAV:workspace-collection-set element.
<!ELEMENT workspace-collection-set (href*)>so if there's an XML request body, it MUST be a DAV:options XML element 🙈 and if a successful request gets an XML response body, it MUST be a DAV:options-response XML element.
if DAV:workspace-collection-set shows up in the request body, the successful response body MUST contain a DAV:workspace-collection-set element listing the collections that may contain workspaces 💜 an identified collection MAY be the root of a whole tree of collections, and all of them may hold workspaces. servers can each run different parts of the URL namespace, so different resources on the same host MAY have different DAV:workspace-collection-set values. and the identified collections MAY live on different hosts from the resource. wild, right? 🌈
6.4.1 Example - OPTIONS 🔥
REQUEST
OPTIONS /doc HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options xmlns:D="DAV:">
<D:version-history-collection-set/>
<D:workspace-collection-set/>
</D:options>RESPONSE
HTTP/1.1 200 OK
DAV: 1
DAV: version-control,checkout-in-place,version-history,workspace
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:options-response xmlns:D="DAV:">
<D:version-history-collection-set>
<D:href>http://repo.webdav.org/his</D:href>
</D:version-history-collection-set>
<D:workspace-collection-set>
<D:href>http://www.webdav.org/public/ws</D:href>
<D:href>http://www.webdav.org/private/ws</D:href>
</D:workspace-collection-set>
</D:options-response>in this example the server says it gives Class 1 DAV support and basic-server-workspace versioning support 🦋 it also shares where the version history resources and the workspace resources live. so cute, the server is literally telling you the whole map 🗺️✨
6.5 Additional DELETE Semantics 💀
Additional Postconditions:
(DAV:delete-workspace-members): this one's serious 😭 if a workspace gets deleted, any resource whose DAV:workspace property points at that workspace MUST be deleted too. no leftovers, no cap 🫠
6.6 Additional MOVE Semantics 🦋
Additional Postconditions:
(DAV:workspace-member-moved): if the request-URL did not identify a workspace, the DAV:workspace of the destination MUST have been updated to match the DAV:workspace of the destination's parent collection 🌸
(DAV:workspace-moved): if the request-URL identified a workspace, any reference to that workspace in a DAV:workspace property MUST have been updated to point at the workspace's new location. it's giving "everyone gets the new address" 📬💖
6.7 Additional VERSION-CONTROL Semantics 💅
a VERSION-CONTROL request can create a new version-controlled resource for an existing version history 🌈 which means you can have version-controlled resources for the same version history in multiple workspaces. main character energy, honestly ✨
Additional Marshalling:
<!ELEMENT version-control ANY>
ANY value: A sequence of elements with at most one DAV:version
element.
<!ELEMENT version (href)>Additional Preconditions:
(DAV:cannot-add-to-existing-history): if the DAV:version-control request body element has a DAV:version element inside it, the request-URL MUST NOT identify a resource 🙅♀️
(DAV:must-be-version): the DAV:href of the DAV:version element MUST identify a version. no vibes-based hrefs here 💜
(DAV:one-version-controlled-resource-per-history-per-workspace): if the DAV:version-control request body names a version, and the request-URL is a member of a workspace, then there MUST NOT already be a version-controlled member of that workspace whose DAV:checked-in or DAV:checked-out property points at any version from the version history of the version in the request body. one per history per workspace, babe, that's the rule 🎀
Additional Postconditions:
(DAV:new-version-controlled-resource): if the request-URL did not identify a resource, a new version-controlled resource exists at the request-URL. its content and dead properties come from the version in the request body, and its DAV:checked-in property identifies that version 🧚
6.7.1 Example - VERSION-CONTROL (using an existing version history) 🌸
REQUEST
VERSION-CONTROL /ws/public/bar.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:version-control xmlns:D="DAV:">
<D:version>
<D:href>http://repo.webdav.org/his/12/ver/V3</D:href>
</D:version>
</D:version-control>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cachein this example a new version-controlled resource gets created at /ws/public/bar.html 🎀 its content and dead properties are copied from http://repo.webdav.org/his/12/ver/V3, so it starts out looking exactly like that version. clone energy 👯♀️
7 UPDATE Feature 🔄
the update feature lets you switch a checked-in version-controlled resource over to the state of another version from its own version history 🦋 basically a glow-up with receipts ✨
7.1 UPDATE Method 💖
the UPDATE method changes the content and dead properties of a checked-in version-controlled resource (the "update target") so they match a specified version (the "update source") from that resource's version history 🫶
the response to an UPDATE request names the resources it modified, so a client can refresh any cached state it's holding. extensions to UPDATE can modify several resources from one UPDATE request too (see Section 12.13) 🌈
Marshalling:
the request body MUST be a DAV:update element 🎀
<!ELEMENT update ANY>
ANY value: A sequence of elements with at most one DAV:version
element and at most one DAV:prop element.
<!ELEMENT version (href)>
prop: see RFC 2518, Section 12.11a successful request's response MUST be a 207 Multi-Status, and the DAV:multistatus XML element in that response body MUST identify every resource modified by the request 🌟 the response itself is a grammar note too:
multistatus: see RFC 2518, Section 12.9and the response MUST include a Cache-Control:no-cache header 🙈
Postconditions:
(DAV:update-content-and-properties): if the DAV:version element in the request body identified a version in the same version history as the DAV:checked-in version of the version-controlled resource at the request-URL, then that resource's content and dead properties MUST match the version named by the DAV:version element, and its DAV:checked-in property MUST identify that version. the request-URL MUST appear in a DAV:response element in the response body 💅
(DAV:report-properties): if DAV:prop is in the request body, the properties it names MUST be reported in the DAV:response elements in the response body 📋✨
7.1.1 Example - UPDATE 🔥
REQUEST
UPDATE /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:update xmlns:D="DAV:">
<D:version>
<D:href>http://repo.webdav.org/his/23/ver/33</D:href>
</D:version>
</D:update>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Cache-Control: no-cache
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/foo.html</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>in this example the content and dead properties of http://repo.webdav.org/his/23/ver/33 get copied onto /foo.html 🎀 and /foo.html's DAV:checked-in property now points at http://repo.webdav.org/his/23/ver/33. glow-up complete 🦋👑
7.2 Additional OPTIONS Semantics 🌷
if the server supports the update feature, it MUST include "update" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods 🫶
8 Label Feature 🏷️
a version "label" is a string that tells one version in a version history apart from all the other versions in that same history 💜 a server can assign a label automatically, or a client can assign one to give the version a meaningful name. a given label can go on at most one version of a given version history, but client-assigned labels can be moved to a different version at any time 🦋 and the same label can show up on versions from different version histories, just not twice in one history. iykyk 🙈
for certain methods, if the request-URL identifies a version-controlled resource, a label can be sent in a Label request header (see Section 8.3) so the method runs on the version picked by that label from that resource's version history ✨
8.1 Additional Version Properties 🧚
the label feature adds the following REQUIRED property for a version 🎀
8.1.1 DAV:label-name-set (protected) 🌸
this property holds the labels that currently pick out this version 💖
<!ELEMENT label-name-set (label-name*)>
<!ELEMENT label-name (#PCDATA)>
PCDATA value: string8.2 LABEL Method ✨
Okay so a LABEL request can be aimed at a version to change which labels pick that version 💅 The case of a label name MUST be preserved when it's stored and retrieved, so no sneaky lowercasing 🙈 When a server compares two label names to see if they match, it SHOULD do a case-sensitive, URL-escaped, UTF-8 encoded comparison of the two names 🌸
If a LABEL request is applied to a checked-in version-controlled resource, the operation MUST be applied to the DAV:checked-in version of that version-controlled resource 🫶
Marshalling:
The request body MUST be a DAV:label element.
<!ELEMENT label ANY>
ANY value: A sequence of elements with at most one DAV:add,
DAV:set, or DAV:remove element.
<!ELEMENT add (label-name)>
<!ELEMENT set (label-name)>
<!ELEMENT remove (label-name)>
<!ELEMENT label-name (#PCDATA)>
PCDATA value: stringThe request MAY include a Label header.
The request MAY include a Depth header 🎀 If there's no Depth header, Depth:0 is assumed. Standard depth semantics apply, so the request hits the collection at the request-URL and every member of that collection that fits the Depth value. If a Depth header is included and the request fails on any resource, the response MUST be a 207 Multi-Status that identifies all resources for which the request has failed 😭
If a response body for a successful request is included, it MUST be a DAV:label-response XML element.
<!ELEMENT label-response ANY>The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:must-be-checked-in): If the request-URL identifies a version-controlled resource, the version-controlled resource MUST be checked in.
(DAV:must-select-version-in-history): If a Label request header is included and the request-URL identifies a version-controlled resource, the specified label MUST select a version in the version history of the version-controlled resource.
(DAV:add-must-be-new-label): If DAV:add is specified in the request body, the specified label MUST NOT appear in the DAV:label-name-set of any version in the version history of that version-controlled resource.
(DAV:label-must-exist): If DAV:remove is specified in the request body, the specified label MUST appear in the DAV:label-name-set of that version.
Postconditions:
(DAV:add-or-set-label): If DAV:add or DAV:set is specified in the request body, the specified label MUST appear in the DAV:label-name-set of the specified version, and MUST NOT appear in the DAV:label-name-set of any other version in the version history of that version.
(DAV:remove-label): If DAV:remove is specified in the request body, the specified label MUST NOT appear in the DAV:label-name-set of any version in the version history of that version.
8.2.1 Example - Setting a label 🦋
>>REQUEST
LABEL /foo.html HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:label xmlns:D="DAV:">
<D:set>
<D:label-name>default</D:label-name>
</D:set>
</D:label>
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cacheIn this example, the label "default" is applied to the DAV:checked-in version of /foo.html 🌈
8.3 Label Header 🧚
For certain methods (e.g. GET, PROPFIND), if the request-URL identifies a version-controlled resource, you can pass a label in a Label request header. That makes the method act on the version picked by that label from the version history of the resource 💜
The value of a Label header is the label name, encoded using URL-escaped UTF-8. For example, the label "release B.3" is sent like this:
Label: release%20B.3A Label header MUST have no effect on a request whose request-URL does not identify a version-controlled resource. In particular, it MUST have no effect on a request whose request-URL identifies a version or a version history 🙅♀️
A server MUST return an HTTP-1.1 Vary header containing Label in a successful response to a cacheable request (e.g., GET) that includes a Label header 🍓
8.4 Additional OPTIONS Semantics ⭐
If the server supports the label feature, it MUST include "label" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods 👑
8.5 Additional GET Semantics 🌸
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is included and the request-URL identifies a version-controlled resource, the specified label MUST select a version in the version history of the version-controlled resource.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL identifies a version-controlled resource and a Label request header is included, the response MUST contain the content of the specified version rather than that of the version-controlled resource.
8.6 Additional PROPFIND Semantics 🔥
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is included and the request-URL identifies a version-controlled resource, the specified label MUST select a version in the version history of the version-controlled resource.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL identifies a version-controlled resource and a Label request header is included, the response MUST contain the properties of the specified version rather than that of the version-controlled resource.
8.7 Additional COPY Semantics 🎀
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is included and the request-URL identifies a version-controlled resource, the specified label MUST select a version in the version history of the version-controlled resource.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL identifies a version-controlled resource and a Label request header is included, the request MUST have copied the properties and content of the specified version rather than that of the version-controlled resource.
8.8 Additional CHECKOUT Semantics 💖
If the server supports the working-resource option, a LABEL header may be included to check out the version selected by the specified label 🧁
Additional Marshalling:
The request MAY include a Label header.
Additional Preconditions:
(DAV:must-select-version-in-history): If a Label request header is included and the request-URL identifies a version-controlled resource, the specified label MUST select a version in the version history of the version-controlled resource.
(DAV:must-not-have-label-and-apply-to-version): If a Label request header is included, the request body MUST NOT contain a DAV:apply-to-version element.
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If the request-URL identifies a checked-in version-controlled resource, and a Label request header is included, the CHECKOUT MUST have been applied to the version selected by the specified label, and not to the version-controlled resource itself.
8.9 Additional UPDATE Semantics 🦋
If the request body of an UPDATE request contains a DAV:label-name element, the update target is the resource identified by the request-URL, and the update source is the version selected by the specified label from the version history of the update target 🌈
Additional Marshalling:
<!ELEMENT update ANY>
ANY value: A sequence of elements with at most one DAV:label-name
or DAV:version element (but not both).
<!ELEMENT label-name (#PCDATA)>
PCDATA value: stringThe request MAY include a Depth header. If no Depth header is included, Depth:0 is assumed. Standard depth semantics apply, and the request is applied to the collection identified by the request-URL and to all members of the collection that satisfy the Depth value. If a Depth header is included and the request fails on any resource, the response MUST be a 207 Multi-Status that identifies all resources for which the request has failed 😭
Additional Preconditions:
(DAV:must-select-version-in-history): If the request includes a DAV:label-name element in the request body, the label MUST select a version in the version history of the version-controlled resource identified by the request-URL.
(DAV:depth-update): If the request includes a Depth header, standard depth semantics apply, and the request is applied to the collection identified by the request-URL and to all members of the collection that satisfy the Depth value. The request MUST be applied to a collection before being applied to any members of that collection, since an update of a version-controlled collection might change the membership of that collection 🧚
Additional Postconditions:
(DAV:apply-request-to-labeled-version): If a DAV:label-name element appears in the request body, the content and dead properties of the version-controlled resource must have been updated to be those of the version selected by that label 💅
9 Working-Resource Feature 👑
The working-resource feature is an alternative to the workspace feature for supporting parallel development 💜 The big difference is where the setup lives. With workspaces, the desired configuration of versions and checked-out resources is kept on the server. With working resources, it's kept on the client 🫶 That keeps the server simpler, but it means you can't reach your configuration from clients in other places, like another office, home, or while you're traveling ✈️
There's another difference too. Workspaces shield clients from a logical change that renames shared resources until that change is finished and tested. With working resources, every client uses one shared set of version-controlled resources, so everyone sees the result of a MOVE the moment it happens 👀
If a server supports the working-resource feature but not the checkout-in-place feature, a CHECKOUT request can only be used to create a working resource, and it cannot be used to check out a version-controlled resource 🎀 If a server supports the checkout-in-place feature but not the working-resource feature, a CHECKOUT can only be used to change the state of a version-controlled resource from checked-in to checked-out 🌸
9.1 Additional Version Properties 🦋
The working-resource feature introduces the following REQUIRED properties for a version.
9.1.1 DAV:checkout-fork 🌈
This property is defined in Section 4.1.1.
9.1.2 DAV:checkin-fork ⭐
This property is defined in Section 4.1.2.
9.2 Working Resource Properties 🧁
The working-resource feature introduces the following REQUIRED properties for a working resource. Since a working resource is a checked-out resource, it also has any property defined in this document for a checked-out resource 💖
9.2.1 DAV:auto-update (protected) 🎀
okay so this one is the protected property, meaning it's server-managed bestie 🫶 The DAV:auto-update property identifies the version-controlled resource that will get updated when the working resource is checked in.
<!ELEMENT auto-update (href)>9.2.2 DAV:checkout-fork 🦋
this one's already defined in Section 4.2.1, so go check it there ✨
9.2.3 DAV:checkin-fork 🌸
same deal, this one lives in Section 4.2.2 💅
9.3 CHECKOUT Method (applied to a version) 🧚
okay this is the moment 😭 A CHECKOUT request aimed at a version creates a brand new working resource. The content and dead properties of that working resource are a copy of the version you checked out. iconic, right?
Marshalling:
- If a request body is included, it MUST be a
DAV:checkoutXML element.
<!ELEMENT checkout ANY>ANY value: a sequence of elements with at most one DAV:apply-to-version and at most one DAV:fork-ok element.
<!ELEMENT apply-to-version EMPTY>
<!ELEMENT fork-ok EMPTY>- If a response body for a successful request is included, it MUST be a
DAV:checkout-responseXML element.
<!ELEMENT checkout-response ANY>- The response MUST include a
Locationheader. - The response MUST include a
Cache-Control:no-cacheheader.
Preconditions:
- (
DAV:checkout-of-version-with-descendant-is-forbidden): See Section 4.3. 🙈 - (
DAV:checkout-of-version-with-descendant-is-discouraged): See Section 4.3. - (
DAV:checkout-of-checked-out-version-is-forbidden): See Section 4.3. - (
DAV:checkout-of-checked-out-version-is-discouraged): See Section 4.3.
Postconditions:
- (
DAV:create-working-resource): If the request-URL identified a version, theLocationresponse header MUST contain the URL of a new working resource. TheDAV:checked-outproperty of the new working resource MUST identify the version that was checked out. The content and dead properties of the working resource MUST be copies of the content and dead properties of theDAV:checked-outversion. TheDAV:predecessor-setproperty of the working resource MUST be initialized to be the version identified by the request-URL. TheDAV:auto-updateproperty of the working resource MUST NOT exist. 💖 - (
DAV:create-working-resource-from-checked-in-version): If the request-URL identified a version-controlled resource, andDAV:apply-to-versionis specified in the request body, the CHECKOUT is applied to theDAV:checked-inversion of the version-controlled resource, and not the version-controlled resource itself. A new working resource is created and the version-controlled resource remains checked-in. TheDAV:auto-updateproperty of the working resource MUST identify the version-controlled resource.
9.3.1 Example - CHECKOUT of a version ✨
REQUEST
CHECKOUT /his/12/ver/V3 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/wr/157
Cache-Control: no-cacheokay so in this example, the version at http://repo.webdav.org/his/12/ver/V3 gets checked out, and the new working resource lives at http://repo.webdav.org/wr/157. slay 💅
9.4 CHECKIN Method (applied to a working resource) 🌈
A CHECKIN request aimed at a working resource produces a new version whose content and dead properties are copies of the working resource's. Here's the lowkey twist 👀 If the DAV:auto-update property of the working resource got set because it was created by applying a CHECKOUT with the DAV:apply-to-version flag to a version-controlled resource, the CHECKIN request will also update the content and dead properties of that version-controlled resource to match the new version.
Marshalling:
- If a request body is included, it MUST be a
DAV:checkinXML element.
<!ELEMENT checkin ANY>ANY value: a sequence of elements with at most one DAV:fork-ok element.
<!ELEMENT fork-ok EMPTY>- If a response body for a successful request is included, it MUST be a
DAV:checkin-responseXML element.
<!ELEMENT checkin-response ANY>- The response MUST include a
Cache-Control:no-cacheheader.
Preconditions:
- (
DAV:must-be-checked-out): See Section 4.4. - (
DAV:version-history-is-tree) See Section 4.4. - (
DAV:checkin-fork-forbidden): See Section 4.4. - (
DAV:checkin-fork-discouraged): See Section 4.4. - (
DAV:no-overwrite-by-auto-update): If theDAV:auto-updateproperty for the checked-out resource identifies a version-controlled resource, at least one of the versions identified by theDAV:predecessor-setproperty of the checked-out resource MUST identify a version that is either the same as or a descendant of the version identified by theDAV:checked-inproperty of that version-controlled resource. 🙅♀️
Postconditions:
- (
DAV:create-version): See Section 4.4. - (
DAV:initialize-version-content-and-properties): See Section 4.4. - (
DAV:auto-update): If theDAV:auto-updateproperty of the checked-out resource identified a version-controlled resource, an UPDATE request with the new version MUST have been applied to that version-controlled resource. 🔥 - (
DAV:delete-working-resource): If the request-URL identifies a working resource and ifDAV:keep-checked-outis not specified in the request body, the working resource is deleted. bye bye 👋
9.4.1 Example - CHECKIN of a working resource 🦋
REQUEST
CHECKIN /wr/157 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0RESPONSE
HTTP/1.1 201 Created
Location: http://repo.webdav.org/his/23/ver/15
Cache-Control: no-cachein this one, the working resource /wr/157 checks in, and a new version gets created at http://repo.webdav.org/his/23/ver/15. ✨
9.5 Additional OPTIONS Semantics 🌸
okay so if the server supports the working-resource feature, it MUST include "working-resource" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods. no skipping 🫶
9.6 Additional COPY Semantics 🍓
Additional Postconditions:
- (
DAV:copy-creates-new-resource): The result of copying a working resource is a new non-version-controlled resource at the destination of the COPY. The new resource MAY automatically be put under version control, but the resulting version-controlled resource MUST be associated with a new version history created for that new version-controlled resource. 🧠
9.7 Additional MOVE Semantics 💜
Additional Preconditions:
- (
DAV:cannot-rename-working-resource): If the request-URL identifies a working resource, the request MUST fail. 🙈
Additional Postconditions:
- (
DAV:update-auto-update): If the request-URL identified a version-controlled resource, anyDAV:auto-updateproperties that identified that version-controlled resource MUST have been updated to contain the new location of that version-controlled resource. 🔁
10 Advanced Versioning Features ✨
okay bestie, this is where it gets really spicy 🌶️ Advanced versioning is all about the problems of parallel development and configuration management for multiple sets of interrelated resources. Traditionally, software artifacts like requirements, design docs, code, and test cases have been the main focus of configuration management. Websites are another totally complex class of information artifacts (HTML, graphics, sound, CGI, and more) that benefit from configuration management too. The advanced versioning features for coordinating concurrent change give you the infrastructure to manage large, evolving websites efficiently and in a controlled way. main character energy 👑
10.1 Advanced Versioning Packages 🧚♀️
so a server MAY support any combination of advanced versioning features 💅 But to keep things simple for a WebDAV advanced versioning client, a WebDAV advanced versioning server SHOULD support one of the following packages:
- Advanced-Server-Workspace Package: basic-server-workspace package plus all advanced features
- Advanced-Client-Workspace Package: basic-client-workspace package plus all advanced features
The advanced-server-workspace package supports advanced versioning capabilities for a client with no persistent state. The advanced-client-workspace package supports advanced versioning capabilities for a client that keeps configuration state on the client. And ngl, a server that supports both advanced workspace packages will interoperate with all versioning clients. periodt 🌈
10.2 Advanced Versioning Terms ✨
okay bestie, here are the extra terms the advanced versioning features throw around 💅 the spec says they're "used by the advanced versioning features," so these are the words you'll see everywhere 🦋
Collection 🗂️
A "collection" is a resource whose state is made of more than content and properties. It also has a set of named "bindings", and each binding identifies what RFC 2518 calls an "internal member" of the collection 💜 ngl a binding is not a resource. It's just a piece of the collection's state that maps a binding name (a URL segment) to a resource (an internal member of the collection) 🧚
Collection Version Resource 📦
A "collection version resource", or simply "collection version", captures the dead properties of a version-controlled collection, plus the names of its version-controlled bindings (see Section 14) 🌸 a version-controlled binding is a binding to a version-controlled resource. If the checkout-in-place feature is supported, you can make a collection version by checking out and then checking in a version-controlled collection 🙌 and if the working-resource feature is supported, you can make one by checking out a collection version (to create a "working collection") and then checking in that working collection 🫶
Configuration 🧩
A "configuration" is a set of resources made of a root collection plus all members (not just internal members) of that root collection that are not members of another configuration 💖 the root collection is called the "configuration root", and the members of this set are called the "members of the configuration". Lowkey important: a collection (one single resource) is very different from a configuration (a whole set of resources) 🙈
Baseline Resource 📸
A "baseline resource", or simply "baseline", of a collection is a version of the configuration rooted at that collection (see Section 12) ✨ a baseline captures the DAV:checked-in version of every version-controlled member of that configuration. Again, a collection version captures the state of a single resource, while a collection baseline captures the state of a set of resources, so they are very different 💅
Baseline-Controlled Collection 🎀
A "baseline-controlled collection" is a collection that baselines can be created from (see Section 12) 👑
Version-Controlled Configuration Resource 🪄
A "version-controlled configuration resource", or simply "version-controlled configuration", is a special kind of version-controlled resource. It's associated with a baseline-controlled collection and is used to create and access baselines of that collection (see Section 12) 🦋 when a collection is both version-controlled and baseline-controlled, a client can make a new version of the collection by checking out and checking in that collection. It can also make a new baseline of the collection by checking out and checking in the version-controlled configuration of that collection 🌈
Activity Resource 🏃♀️
An "activity resource", or simply "activity", is a resource that selects a set of versions that go with one logical change 💜 the versions picked from a given version history form a single line of descent through that history (see Section 13) 🍓
11 Merge Feature 🔀
okay so this part is about getting other people's changes (new versions) into your own stuff 🫶 the big no-no is just updating your version-controlled resources in your workspace with their new versions, because that could literally back out changes you already made 😭 so instead, the versions made in another workspace should be "merged" into your version-controlled resources ✨
the version history of a version-controlled resource has all the info needed to figure out the result of the merge 🧠 basically, the merge should pick whichever version is later in the line of descent from the root version. But if the versions are on different lines of descent (neither one is a descendant of the other), then neither version gets picked 🙅♀️ instead, a brand new version gets created that holds the logical merge of the content and dead properties of those versions 🌸 the MERGE request can check out each version-controlled resource that needs this kind of merge and set the DAV:merge-set property of each checked-out resource to identify the version to be merged. Then you are responsible for editing the content and dead properties of the checked-out resource so it represents the logical merge of that version, and then adding that version to the DAV:predecessor-set of the checked-out resource 💅
heads up bestie: the server is allowed to do the merge automatically if it's capable of it. If it does, it MAY update the content, dead properties, and DAV:predecessor-set of the checked-out resource itself 🤖 but before you check in that automatically merged resource, you are responsible for checking that the automatic merge is correct 👀
11.1 Additional Checked-Out Resource Properties 🎁
the merge feature brings in the following REQUIRED properties for a checked-out resource 💜
11.1.1 DAV:merge-set 🔗
this property identifies each version that is to be merged into this checked-out resource 🌷
<!ELEMENT merge-set (href*)>11.1.2 DAV:auto-merge-set 🤖
this property identifies each version that the server has merged into this checked-out resource 💖 the client should confirm the merge was done correctly before moving a URL from the DAV:auto-merge-set to the DAV:predecessor-set of a checked-out resource 🫶
<!ELEMENT auto-merge-set (href*)>11.2 MERGE Method ✨
okay so the MERGE method takes one version (the "merge source") and logically merges it into a version-controlled resource (the "merge target") 🔀 it's giving teamwork, bestie 💖 If the merge source is neither an ancestor nor a descendant of the DAV:checked-in or DAV:checked-out version of the merge target, the MERGE checks out the merge target (if it isn't already checked out) and adds the URL of the merge source to the DAV:merge-set of the merge target. After that, it's on the client to update the content and dead properties of the checked-out merge target so they reflect the logical merge of the merge source into the current state of the merge target 🫶 When the client finishes, it marks that by deleting the merge source URL from the DAV:merge-set of the checked-out merge target and adding it to the DAV:predecessor-set.
But there's a safety net 🚨 As an error check for a client who forgets to finish a merge, the server MUST fail an attempt to CHECKIN a version-controlled resource with a non-empty DAV:merge-set. no excuses 💅
When a server can automatically update the content and dead properties of the merge target to reflect the logical merge of the merge source, it may do so, unless DAV:no-auto-merge is specified in the MERGE request body. To let the client know a merge source was auto-merged, the MERGE request MUST add the URL of the auto-merged source to the DAV:auto-merge-set property of the merge target, and not to the DAV:merge-set property. The client says "yep, I checked, the auto-merge is valid" by deleting the merge source URL from the DAV:auto-merge-set and adding it to the DAV:predecessor-set ✨
Multiple merge sources can go in a single MERGE request. The set of merge sources is determined by the DAV:source element of the MERGE request body, like this:
- If
DAV:sourceidentifies a version, that version is a merge source. - If
DAV:sourceidentifies a version-controlled resource, theDAV:checked-inversion of that version-controlled resource is a merge source. - If
DAV:sourceidentifies a collection, theDAV:checked-inversion of each version-controlled resource that is a member of that collection is a merge source.
The request-URL identifies the set of possible merge targets. If the request-URL identifies a collection, any member of the configuration rooted at the request-URL is a possible merge target. The merge target of a particular merge source is the version-controlled or checked-out resource whose DAV:checked-in or DAV:checked-out version is from the same version history as the merge source. If a merge source has no merge target, that merge source is ignored 🙈
The MERGE response identifies the resources that a client must modify to complete the merge. It also identifies the resources modified by the request, so a client can efficiently update any cached state it is maintaining ⚡
Marshalling:
The request body MUST be a DAV:merge element.
The set of merge sources is determined by the DAV:source element in the request body.
<!ELEMENT merge ANY>
ANY value: A sequence of elements with one DAV:source element, at
most one DAV:no-auto-merge element, at most one DAV:no-checkout
element, at most one DAV:prop element, and any legal set of
elements that can occur in a DAV:checkout element.
<!ELEMENT source (href+)>
<!ELEMENT no-auto-merge EMPTY>
<!ELEMENT no-checkout EMPTY>
prop: see RFC 2518, Section 12.11The response for a successful request MUST be a 207 Multi-Status, where the DAV:multistatus XML element in the response body identifies all resources that have been modified by the request.
multistatus: see RFC 2518, Section 12.9The response to a successful request MUST include a Location header containing the URL for the new version created by the checkin.
The response MUST include a Cache-Control:no-cache header.
Preconditions:
- (DAV:cannot-merge-checked-out-resource): The
DAV:sourceelement MUST NOT identify a checked-out resource. If theDAV:sourceelement identifies a collection, the collection MUST NOT have a member that is a checked-out resource. - (DAV:checkout-not-allowed): If
DAV:no-checkoutis specified in the request body, it MUST be possible to perform the merge without checking out any of the merge targets. - All preconditions of the CHECKOUT operation apply to the checkouts performed by the request.
Postconditions:
- (DAV:ancestor-version): If a merge target is a version-controlled or checked-out resource whose
DAV:checked-inversion orDAV:checked-outversion is the merge source or is a descendant of the merge source, the merge target MUST NOT have been modified by the MERGE. - (DAV:descendant-version): If the merge target was a checked-in version-controlled resource whose
DAV:checked-inversion was an ancestor of the merge source, anUPDATEoperation MUST have been applied to the merge target to set its content and dead properties to be those of the merge source. If theUPDATEmethod is not supported, the merge target MUST have been checked out, the content and dead properties of the merge target MUST have been set to those of the merge source, and the merge source MUST have been added to theDAV:auto-merge-setof the merge target. The merge target MUST appear in aDAV:responseXML element in the response body. - (DAV:checked-out-for-merge): If the merge target was a checked-in version-controlled resource whose
DAV:checked-inversion was neither a descendant nor an ancestor of the merge source, a CHECKOUT MUST have been applied to the merge target. All XML elements in theDAV:mergeXML element that could appear in aDAV:checkoutXML element MUST have been used as arguments to the CHECKOUT request. The merge target MUST appear in aDAV:responseXML element in the response body. - (DAV:update-merge-set): If the
DAV:checked-outversion of the merge target is neither equal to nor a descendant of the merge source, the merge source MUST be added to either theDAV:merge-setor theDAV:auto-merge-setof the merge target. The merge target MUST appear in aDAV:responseXML element in the response body. - (DAV:report-properties): If
DAV:propis specified in the request body, the properties specified in theDAV:propelement MUST be reported in theDAV:responseelements in the response body.
If a merge source has been added to the DAV:auto-merge-set, the content and dead properties of the merge target MUST have been modified by the server to reflect the result of a logical merge of the merge source and the merge target. If a merge source has been added to the DAV:merge-set, the content and dead properties of the merge target MUST NOT have been modified by the server. If DAV:no-auto-merge is specified in the request body, the merge source MUST NOT have been added to the DAV:auto-merge-set.
11.2.1 Example - MERGE 🎀
>>REQUEST
MERGE /ws/public HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge xmlns:D="DAV:">
<D:source>
<D:href>http://www.webdav.org/ws/dev/sally</D:href>
</D:source>
</D:merge>>>RESPONSE
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
Cache-Control: no-cache
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://www.webdav.org/ws/public/src/parse.c</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
<D:response>
<D:href>http://www.webdav.org/ws/public/doc/parse.html</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>In this example, the DAV:checked-in versions from the workspace http://www.webdav.org/ws/dev/sally are merged into the version-controlled resources in the workspace http://www.webdav.org/ws/public. The resources /ws/public/src/parse.c and /ws/public/doc/parse.html were modified by the request 🌸
11.3 DAV:merge-preview Report 🔮
A merge preview describes the changes that would result if the versions specified by the DAV:source element in the request body were to be merged into the resource identified by the request-URL (commonly, a collection).
Marshalling:
The request body MUST be a DAV:merge-preview XML element.
<!ELEMENT merge-preview (source)>
<!ELEMENT source (href)>The response body for a successful request MUST be a DAV:merge-preview-report XML element.
<!ELEMENT merge-preview-report
(update-preview | conflict-preview | ignore-preview)*>A DAV:update-preview element identifies a merge target whose DAV:checked-in property would change as a result of the MERGE, and identifies the merge source for that merge target.
<!ELEMENT update-preview (target, version)>
<!ELEMENT target (href)>
<!ELEMENT version (href)>A DAV:conflict-preview element identifies a merge target that requires a merge.
<!ELEMENT conflict-preview (target, common-ancestor, version)>A DAV:common-ancestor element identifies the version that is a common ancestor of both the merge source and the DAV:checked-in or DAV:checked-out version of the merge target.
<!ELEMENT common-ancestor (href)>A DAV:ignore-preview element identifies a version that has no merge target and therefore would be ignored by the merge.
<!ELEMENT ignore-preview (version)>11.3.1 Example - DAV:merge-preview Report 🦋
>>REQUEST
REPORT /ws/public HTTP/1.1
Host: www.webdav.org
Content-type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-preview xmlns:D="DAV:">
<D:source>
<D:href>http://www.webdav.org/ws/dev/fred</D:href>
</D:source>
</D:merge-preview>>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:merge-preview-report xmlns:D="DAV:">
<D:conflict-preview>
<D:target>
<D:href>http://www.webdav.org/ws/public/foo.html</D:href>
</D:target>
<D:common-ancestor>
<D:href>http://repo.webdav.org/his/23/ver/18</D:href>
</D:common-ancestor>
<D:version>
<D:href>http://repo.webdav.org/his/23/ver/42</D:href>
</D:version>
</D:conflict-preview>
<D:update-preview>
<D:target>
<D:href>http://www.webdav.org/ws/public/bar.html</D:href>
</D:target>
<D:version>
<D:href>http://www.repo/his/42/ver/3</D:href>
</D:version>
</D:update-preview>
</D:merge-preview-report>In this example, the merge preview report indicates that version /his/23/ver/42 would be merged in /ws/public/foo.html, and version /his/42/ver/3 would update /ws/public/bar.html if the workspace http://www.webdav.org/ws/dev/fred was merged into the workspace http://www.webdav.org/ws/public. that's the whole preview, bestie 💜
11.4 Additional OPTIONS Semantics 🦋
okay so if the server supports the merge feature, it MUST include "merge" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods. no cap, that's the rule 💅
11.5 Additional DELETE Semantics 🗑️
Additional Postconditions:
(DAV:delete-version-reference): if a version gets deleted, any reference to that version in a DAV:merge-set or DAV:auto-merge-set property MUST be removed. it's gone, gone, gone 👋✨
11.6 Additional CHECKIN Semantics ✅
Additional Preconditions:
(DAV:merge-must-be-complete): the DAV:merge-set and DAV:auto-merge-set of the checked-out resource MUST be empty or not exist. so clean up your merges before you check in, bestie 🧹💖
12 Baseline Feature 🌈
okay so a configuration is basically a root collection plus everything inside it, except anything that belongs to some other configuration 🗂️ ngl that's a lot of stuff. a big configuration can eat a huge chunk of server space, which makes it super expensive to save its state by making a Depth:infinity copy of its root collection. yikes 😭
a baseline is a version resource that captures the state of each version-controlled member of a configuration 📸. a baseline history is a version history whose versions are baselines 🧚. new baselines get made by checking out and then checking in a special kind of version-controlled resource called a version-controlled configuration. it's giving main character energy 👑
a collection that's under baseline control is called a baseline-controlled collection. to keep baseline implementations efficient, the state of a baseline of a collection is limited to a set of versions and their names relative to the collection 🍓. the only things you can do with a baseline are create one from a collection, and restore it or merge it back into a collection. a server MAY automatically put a collection under baseline control when it's created, or a client can use the BASELINE-CONTROL method to put a specified collection under baseline control 🎀
once a configuration gets big, it's super useful to split it into smaller configurations that act as the logical "components" of that configuration 🧩. to show that a baseline of a configuration is logically extended by a component configuration baseline, that component baseline gets captured as a "subbaseline" of the baseline. so cute, right? 🥹
the root collection of a configuration isn't tied to the root collections of its components. so the root collection of a configuration can have a member that is the root collection of one of its components (like configuration /sys/x having component /sys/x/foo), it can be a member of the root collection of one of its components (like configuration /sys/y/z having component /sys/y), or neither (like configuration /sys/x having component /comp/bar) 💅
12.1 Version-Controlled Configuration Properties 🎀
since a version-controlled configuration is a version-controlled resource, it has all the properties of a version-controlled resource 🫶. on top of that, the baseline feature adds the following REQUIRED property for a version-controlled configuration.
12.1.1 DAV:baseline-controlled-collection (protected) 🔒
this property identifies the collection that holds the version-controlled resources whose DAV:checked-in versions are being tracked by this version-controlled configuration. the DAV:version-controlled-configuration of the DAV:baseline-controlled-collection of a version-controlled configuration MUST identify that version-controlled configuration. it's a whole loop, iykyk 🔁
<!ELEMENT baseline-controlled-collection (href)>12.2 Checked-Out Configuration Properties ✏️
since a checked-out configuration is a checked-out resource, it has all the properties of a checked-out resource 💖. the baseline feature also adds the following REQUIRED property for a checked-out configuration.
12.2.1 DAV:subbaseline-set 🧁
this property decides the DAV:subbaseline-set property of the baseline that comes out of checking in this resource.
a server MAY reject attempts to modify the DAV:subbaseline-set of a checked-out configuration. it's giving gatekeeper vibes 🚪
<!ELEMENT subbaseline-set (href*)>12.3 Baseline Properties 📸
the DAV:resourcetype of a baseline MUST be DAV:baseline. since a baseline is a version resource, it has all the properties of a version resource ✨. the baseline feature also adds the following REQUIRED properties for a baseline.
12.3.1 DAV:baseline-collection (protected) 🗂️
this property holds a server-defined URL for a collection. each member of that collection MUST either be a version-controlled resource with the same DAV:checked-in version and relative name as a version-controlled member of the baseline-controlled collection at the time the baseline was created, or be a collection needed to provide the relative name for a version-controlled resource. so everything lines up perfectly 📐🌸
<!ELEMENT baseline-collection (href)>12.3.2 DAV:subbaseline-set (protected) 🧩
the URLs in the DAV:subbaseline-set property MUST identify a set of other baselines. the subbaselines of a baseline are the baselines identified by its DAV:subbaseline-set, plus all subbaselines of those baselines. it's a whole family tree 🌳
<!ELEMENT subbaseline-set (href*)>12.4 Additional Resource Properties 🌟
the baseline feature adds the following REQUIRED property for a resource.
12.4.1 DAV:version-controlled-configuration (computed) 🧚
if the resource is a member of a version-controlled configuration (aka the resource is a collection under baseline control, or is a member of a collection under baseline control), this property identifies that version-controlled configuration.
<!ELEMENT version-controlled-configuration (href)>12.5 Additional Workspace Properties 🏠
the baseline feature adds the following REQUIRED property for a workspace.
12.5.1 DAV:baseline-controlled-collection-set (computed) 💜
this property identifies each member of the workspace that is a collection under baseline control. if the workspace itself is under baseline control, it gets listed too 🫶
<!ELEMENT baseline-controlled-collection-set (href*)>12.6 BASELINE-CONTROL Method 🎉
a collection can be put under baseline control with a BASELINE-CONTROL request. when that happens, the DAV:version-controlled-configuration property of the collection gets set to identify a new version-controlled configuration. that configuration can be checked out and then checked in to make a new baseline for the collection 🍓
if a baseline is specified in the request body, the DAV:checked-in version of the new version-controlled configuration will be that baseline. the collection also gets initialized to contain version-controlled members whose DAV:checked-in versions and relative names are set by the specified baseline 🧁
if no baseline is specified, a new baseline history gets created, containing a baseline that captures the state of the version-controlled members of the collection. the DAV:checked-in version of the version-controlled configuration will be that baseline 📸
Marshalling 📮
if a request body is included, it MUST be a DAV:baseline-control XML element.
<!ELEMENT baseline-control ANY>
ANY value: A sequence of elements with at most one DAV:baseline
element.
<!ELEMENT baseline (href)>if a response body for a successful request is included, it MUST be a DAV:baseline-control-response XML element.
<!ELEMENT baseline-control-response ANY>the response MUST include a Cache-Control:no-cache header. 🙅♀️💾
Preconditions 🚦
(DAV:version-controlled-configuration-must-not-exist): the DAV:version-controlled-configuration property of the collection identified by the request-URL MUST not exist. no double-dipping allowed 🙅♀️
(DAV:must-be-baseline): the DAV:href of the DAV:baseline element in the request body MUST identify a baseline. 📸
(DAV:must-have-no-version-controlled-members): if a DAV:baseline element is specified in the request body, the collection identified by the request-URL MUST have no version-controlled members. it has to be empty, babe 🫧
(DAV:one-baseline-controlled-collection-per-history-per-workspace): if the request-URL identifies a workspace or a member of a workspace, and if a baseline is specified in a DAV:baseline element in the request body, then there MUST NOT be another collection in that workspace whose DAV:version-controlled-configuration property identifies a version-controlled configuration for the baseline history of that baseline. one per history per workspace, no sharing 🚫💅
Postconditions 🏁
(DAV:create-version-controlled-configuration): a new version-controlled configuration is created, and its DAV:baseline-controlled-collection property identifies the collection. ✨
(DAV:reference-version-controlled-configuration): the DAV:version-controlled-configuration of the collection identifies the new version-controlled configuration. 🔗
(DAV:select-existing-baseline): if the request body specifies a baseline, the DAV:checked-in property of the new version-controlled configuration MUST have been set to identify this baseline. a version-controlled member of the collection gets created for each version in the baseline. that member has the content and dead properties of that version, and the same name relative to the collection as the corresponding version-controlled resource had when the baseline was created. any nested collections needed to give a version-controlled member its proper name get created too 🧚🌈
(DAV:create-new-baseline): if no baseline is specified in the request body, the request MUST have created a new baseline history at a server-defined URL, and MUST have created a new baseline in that baseline history. the DAV:baseline-collection of the new baseline MUST identify a collection whose members have the same relative name and DAV:checked-in version as the version-controlled members of the request collection. and the DAV:checked-in property of the new version-controlled configuration MUST identify the new baseline. ta-da 🎀🥳
12.6.1 Example - BASELINE-CONTROL ✨
>>REQUEST 📨
BASELINE-CONTROL /src HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:baseline-control xmlns:D="DAV:">
<D:href>http://www.webdav.org/repo/blh/13/ver/8</D:href>
</D:baseline-control>>>RESPONSE 💌
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 0Okay bestie, so here's the tea 🫖. The /src collection gets put under baseline control and gets filled up with members from an existing baseline 🌈. The server makes a brand new version-controlled configuration (/repo/vcc/128) and links it to /src. Then /src gets set up with version-controlled members whose DAV:checked-in versions are the ones picked by the DAV:baseline-collection (/repo/bc/15) of the baseline you pointed at (/repo/blh/13/ver/8). The diagram below shows what the server's state looks like after all that 🧚
+-------------------------------------+
|Baseline-Controlled Collection |<------+
|/src | |
|-------------------------------------| |
|DAV:version-controlled-configuration +---+ |
+-------------------------------------+ | |
| |
| |
+-------------------------------------+ | |
|Version-Controlled Configuration |<--+ |
|/repo/vcc/128 | |
|-------------------------------------| |
|DAV:baseline-controlled-collection +-------+
|-------------------------------------|
|DAV:checked-in +-------+
+-------------------------------------+ |
|DAV:version-history +---+ |
+-------------------------------------+ | |
| |
| |
+------------------------+ | |
|Baseline History |<---------------+ |
|/repo/blh/13 | |
|------------------------+ |
|DAV:version-set +----------------+ |
+------------------------+ | | | | |
v | v v |
| |
+------------------------+ | |
|Baseline |<-------+-----------+
|/repo/blh/13/ver/8 |
|------------------------+ +--------------+
|DAV:baseline-collection +---->|Collection |
+------------------------+ |/repo/bc/15 |
+--------------+Now for the fun part 🎉. If you want to make new baselines of /src, you check out /repo/vcc/128, create or select new versions for the version-controlled members of /src, and then check in /repo/vcc/128 to capture the current state of those members. Iconic loop, no notes 💅
12.7 DAV:compare-baseline Report 💜
A DAV:compare-baseline report shows you the differences between the baseline named by the request-URL (the "request baseline") and the baseline named in the request body (the "compare baseline") 👀
Marshalling:
The request body MUST be a DAV:compare-baseline XML element.
<!ELEMENT compare-baseline (href)>The response body for a successful request MUST be a DAV:compare-baseline-report XML element.
<!ELEMENT compare-baseline-report
(added-version | deleted-version | changed-version)*>A DAV:added-version element points at a version that is the DAV:checked-in version of a member of the DAV:baseline-collection of the compare baseline. The catch is that no version in that version's history is the DAV:checked-in version of a member of the DAV:baseline-collection of the request baseline 🌸
<!ELEMENT added-version (href)>A DAV:deleted-version element points at a version that is the DAV:checked-in version of a member of the DAV:baseline-collection of the request baseline. Here, though, no version in that version's history is the DAV:checked-in version of a member of the DAV:baseline-collection of the compare baseline 💀
<!ELEMENT deleted-version (href)>A DAV:changed-version element points at two different versions from the same version history. One is the DAV:checked-in version of the DAV:baseline-collection of the request baseline, and the other is the DAV:checked-in version from the compare baseline, in that order 🦋
<!ELEMENT changed-version (href, href)>Preconditions:
(DAV:must-be-baseline): The DAV:href in the request body MUST identify a baseline.
(DAV:baselines-from-same-history): A server MAY require that the baselines being compared come from the same baseline history. Some servers are picky like that 🙈
12.7.1 Example - DAV:compare-baseline Report 🌸
>>REQUEST 📨
REPORT /bl-his/12/bl/14 HTTP/1.1
Host: repo.webdav.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:compare-baseline xmlns:D="DAV:">
<D:href>http://repo.webdav.org/bl-his/12/bl/15</D:href>
</D:compare-baseline>>>RESPONSE 💌
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:compare-baseline-report xmlns:D="DAV:">
<D:added-version>
<D:href>http://repo.webdav.org/his/23/ver/8</D:href>
</D:added-version>
<D:changed-version>
<D:href>http://repo.webdav.org/his/29/ver/12</D:href>
<D:href>http://repo.webdav.org/his/29/ver/19</D:href>
</D:changed-version>
<D:deleted-version>
<D:href>http://repo.webdav.org/his/12/ver/4</D:href>
</D:deleted-version>
</D:compare-baseline-report>In this example, we're comparing baseline 14 and baseline 15 of http://repo.webdav.org/bl-his/12 and spotting all the differences between them ✨
12.8 Additional OPTIONS Semantics 🎀
If a server supports the baseline feature, it MUST include "baseline" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods. No skipping this one, bestie 🫶
12.9 Additional MKCOL Semantics 🧚
Additional Postconditions:
If a server automatically puts a newly created collection under baseline control, all postconditions for BASELINE-CONTROL apply to the MKCOL. So the new collection gets the same treatment as a BASELINE-CONTROL request 🌈
12.10 Additional COPY Semantics 🦋
Additional Postconditions:
If the request creates a new collection at the Destination, and a server automatically puts a newly created collection under baseline control, all postconditions for BASELINE-CONTROL apply to the COPY. Same energy as MKCOL, just with a copy vibe 💅
12.11 Additional CHECKOUT Semantics 👑
Additional Preconditions:
(DAV:must-not-update-baseline-collection): If the request-URL identifies a member of the configuration rooted at the DAV:baseline-collection of a baseline, the request MUST fail. Don't touch the baseline's stuff, babe 🙅♀️
12.12 Additional CHECKIN Semantics 💖
Additional Preconditions:
(DAV:no-checked-out-baseline-controlled-collection-members): If the request-URL identifies a version-controlled configuration, all version-controlled members of the DAV:baseline-controlled-collection of that version-controlled configuration MUST be checked-in. Nothing left hanging out checked out 🫠
(DAV:one-version-per-history-per-baseline): If the request-URL identifies a version-controlled configuration, the set of versions selected by that configuration MUST contain at most one version from any version history. A version counts as "selected" if it's identified by the DAV:checked-in property of any member of the configuration rooted at that configuration's DAV:baseline-controlled-collection, or if it's identified by the DAV:checked-in property of any member of the configuration rooted at the DAV:baseline-collection of any subbaseline of that version-controlled configuration. One version per history, periodt 💅
(DAV:cannot-modify-version-controlled-configuration): If the request-URL identifies a version-controlled member of a baseline-controlled collection whose version-controlled configuration is checked-in, the request MUST fail unless the DAV:auto-version property of that version-controlled configuration will automatically check it out when it gets modified. Basically, no sneaky edits to a checked-in config 🔒
Additional Postconditions:
(DAV:create-baseline-collection): If the request-URL identifies a version-controlled configuration, the DAV:baseline-collection of the new baseline identifies a collection whose members have the same relative name and DAV:checked-in version as the members of the DAV:baseline-controlled-collection of that version-controlled configuration at the time of the request. Copy-paste of the moment, but make it a baseline 📸
(DAV:modify-configuration): If the request-URL identifies a version-controlled member of a baseline-controlled collection, that counts as a modification to the version-controlled configuration of that baseline-controlled collection, and standard auto-versioning semantics apply. So the usual auto-versioning rules kick in 🌟
12.13 Additional UPDATE Semantics 🎀
okay so UPDATE gets extra rules when the thing being updated is a configuration, bestie 💅 Here's the tea:
Additional Preconditions:
(DAV:baseline-controlled-members-must-be-checked-in): If the request-URL identifies a version-controlled configuration, then all version-controlled members of the DAV:baseline-controlled-collection of that version-controlled configuration MUST be checked-in. No loose members allowed 🙅♀️
(DAV:must-not-update-baseline-collection): If the request-URL identifies a member of the configuration rooted at the DAV:baseline-collection of a baseline, the request MUST fail. You can't touch the baseline's own stuff, periodt 🚫
(DAV:cannot-modify-version-controlled-configuration): If the request updates the DAV:checked-in property of any version-controlled member of a baseline-controlled collection whose version-controlled configuration is checked-in, the request MUST fail, unless the DAV:auto-version property of that version-controlled configuration will automatically check out that version-controlled configuration when it is modified. So the only way through is auto-versioning doing the checkout for you ✨
Additional Postconditions:
(DAV:set-baseline-controlled-collection-members): If the request updated the DAV:checked-in property of a version-controlled configuration, then the version-controlled members of the DAV:baseline-controlled-collection of that version-controlled configuration MUST have been updated so they have the same relative name, content, and dead properties as the members of the DAV:baseline-collection of the baseline. In particular:
- A version-controlled member for a given version history MUST have been deleted if there is no version-controlled member for that version history in the
DAV:baseline-collectionof the baseline. 🗑️ - A version-controlled member for a given version history MUST have been renamed if its name relative to the baseline-controlled collection is different from that of the version-controlled member for that version history in the
DAV:baseline-collectionof the baseline. ✏️ - A new version-controlled member MUST have been created for each member of the
DAV:baseline-collectionof the baseline for which there is no corresponding version-controlled member in the baseline-controlled collection. 🌱 - An UPDATE request MUST have been applied to each version-controlled member for a given version history whose
DAV:checked-inversion is not the same as that of the version-controlled member for that version history in theDAV:baseline-collectionof the baseline. 🔁
(DAV:update-subbaselines): If the request updated a version-controlled configuration whose DAV:baseline-controlled-collection contains a baseline-controlled member for one of the subbaselines of the request baseline, then the DAV:checked-in property of the version-controlled configuration of that baseline-controlled member MUST have been updated to be that subbaseline. If the request updated a version-controlled configuration whose DAV:baseline-controlled-collection is a member of a workspace that contains a baseline-controlled member for one of the subbaselines of the request baseline, then the DAV:checked-in property of the version-controlled configuration of that baseline-controlled member MUST have been updated to be that subbaseline. Subbaselines come along for the ride 🧚
(DAV:modify-configuration): If the request updated the DAV:checked-in property of any version-controlled member of a baseline-controlled collection, and if this DAV:checked-in property differs from the DAV:checked-in property of the corresponding version-controlled member of the DAV:baseline-collection of the DAV:checked-in baseline of the DAV:version-controlled-configuration of the baseline-controlled collection, then this is a modification to that version-controlled configuration, and standard auto-versioning semantics apply. 💜
12.14 Additional MERGE Semantics 🦋
If the merge source is a baseline, the merge target is a version-controlled configuration for the baseline history of that baseline, where the baseline-controlled collection of that version-controlled configuration is a member of the collection identified by the request-URL. So the baseline goes in, and the matching config comes out 🌸
Additional Preconditions:
(DAV:must-not-update-baseline-collection): Same semantics as UPDATE (see Section 12.13). Same rule, same vibe 💅
(DAV:cannot-modify-version-controlled-configuration): Same semantics as UPDATE (see Section 12.13). Still locked down, bestie 🔒
Additional Postconditions:
(DAV:merge-baseline): If the merge target is a version-controlled configuration whose DAV:checked-out baseline is not a descendant of the merge baseline, then the merge baseline MUST have been added to the DAV:auto-merge-set of a version-controlled configuration. The DAV:checked-in version of each member of the DAV:baseline-collection of that baseline MUST have been merged into the DAV:baseline-controlled-collection of that version-controlled configuration. Merge it all in 🫶
(DAV:merge-subbaselines): If the merge target is a version-controlled configuration whose DAV:baseline-controlled-collection contains a baseline-controlled member for one of the subbaselines of the merge baseline, then that subbaseline MUST have been merged into the version-controlled configuration of that baseline-controlled member. If the merge target is a version-controlled configuration whose DAV:baseline-controlled-collection is a member of a workspace that contains a baseline-controlled member for one of the subbaselines of the merge baseline, then that subbaseline MUST have been merged into the version-controlled configuration of that baseline-controlled member. Subbaselines get merged too, obviously 🧁
(DAV:set-baseline-controlled-collection-members): Same semantics as UPDATE (see Section 12.13). ✨
(DAV:modify-configuration): Same semantics as UPDATE (see Section 12.13). 👑
13 Activity Feature 🌈
An activity is a resource that selects a set of versions that are on a single "line of descent", where a line of descent is a sequence of versions connected by successor relationships. If an activity selects versions from multiple version histories, the versions selected in each version history must be on a single line of descent. Activities are basically the main character of this whole section 💖
A common problem that motivates the use of activities is that it is often desirable to perform several different logical changes in a single workspace, and then selectively merge a subset of those logical changes into other workspaces. An activity can represent a single logical change, where the activity tracks all the resources that were modified to effect that one change. When a version-controlled resource is checked out, the user specifies which activity should be associated with a new version that will be created when that resource is checked in. Later, a particular logical change can be picked for merging into another workspace by naming the right activity in a MERGE request 🎯
Another common problem is that although a version-controlled resource may need multiple lines of descent, all work done by members of a given team must be on a single line of descent, so nobody merges into each other's stuff. An activity resource handles that. When a version-controlled resource is checked out, a client can ask for an existing activity to be used, or for a new activity to be created. Activity semantics then make sure that all versions in a given version history that are associated with an activity are on a single line of descent. If everyone on a team shares a common activity (or sub-activities of a common activity), then every change that team makes lands on a single line of descent 🫶
The following diagram illustrates activities. Version V5 is the latest version of foo.html selected by activity Act-2, and version V8 is the latest version of bar.html selected by activity Act-2.
foo.html History bar.html History
+---+ +---+
Act-1| |V1 Act-1| |V6
+---+ +---+
| |
| |
+---+ +---+
Act-1| |V2 Act-2| |V7
+---+ +---+
/ \ |
/ \ |
+---+ +---+ +---+
Act-1| |V3 Act-2| |V4 Act-2| |V8
+---+ +---+ +---+
| |
| |
+---+ +---+
Act-2| |V5 Act-3| |V9
+---+ +---+Activities go by lots of names in existing versioning systems 🍓 When an activity captures a logical change, it's commonly called a "change set". When an activity captures a line of descent, it's commonly called a "branch". When a system supports both branches and change sets, it's often useful to require that a particular change set happen on a particular branch. This relationship can be captured by making the change set activity a "subactivity" of the branch activity. Nested activities, iconic 🦋
13.1 Activity Properties 💅
The DAV:resourcetype of an activity MUST be DAV:activity. Activities have to be the right type, no exceptions 👑
The activity feature introduces the following REQUIRED properties for an activity.
13.1.1 DAV:activity-version-set (computed) 🌸
This property identifies each version whose DAV:activity-set property identifies this activity. Multiple versions of a single version history can be selected by an activity's DAV:activity-version-set property, but all DAV:activity-version-set versions from a given version history must be on a single line of descent from the root version of that version history. Single line of descent, every single time 🧵
<!ELEMENT activity-version-set (href*)>13.1.2 DAV:activity-checkout-set (computed) 🎀
This property identifies each checked-out resource whose DAV:activity-set identifies this activity. Who's currently working on it, basically 👀
<!ELEMENT activity-checkout-set (href*)>13.1.3 DAV:subactivity-set 💖
This property identifies each activity that forms a part of the logical change being captured by this activity. An activity behaves as if its DAV:activity-version-set is extended by the DAV:activity-version-set of each activity identified in the DAV:subactivity-set. In particular, the versions in this extended set MUST be on a single line of descent, and when an activity selects a version for merging, the latest version in this extended set is the one that will be merged. Latest one wins, no debate 🏆
A server MAY reject attempts to modify the DAV:subactivity-set of an activity. Servers get a little say here 🙈
<!ELEMENT subactivity-set (href*)>13.1.4 DAV:current-workspace-set (computed) 🧚
This property identifies each workspace whose DAV:current-activity-set identifies this activity. Basically a guest list for workspaces 🌈
<!ELEMENT current-workspace-set (href*)>13.2 Additional Version Properties 🫧
The activity feature introduces the following REQUIRED property for a version.
13.2.1 DAV:activity-set ✨
okay so this one is the property that tells you which activities a version belongs to 💅 it decides which logical changes that version contributes to, and which lines of descent it shows up on 🌸 a server MAY restrict the DAV:activity-set to identify a single activity, and a server MAY refuse to let the value of a version's DAV:activity-set get modified 🙈
<!ELEMENT activity-set (href*)>13.3 Additional Checked-Out Resource Properties 🎀
the activity feature brings in the following REQUIRED properties for a checked-out resource 💖
13.3.1 DAV:unreserved 🦋
this property on a checked-out resource says whether the DAV:activity-set of another checked-out resource in the same version history can include an activity that's in this resource's DAV:activity-set 👀
ngl this one gets messy fast 😭 an activity has to form a single line of descent through a version history, so if you check out several resources from one history unreserved into the same activity, only the first CHECKIN will succeed 💀 before any of the others can be checked in, the user has to merge in the latest version that activity selected from that history, and then change the DAV:predecessor-set of that checked-out resource so it points at that version 🫶
<!ELEMENT unreserved (#PCDATA)>
PCDATA value: boolean13.3.2 DAV:activity-set 🌈
this property on a checked-out resource decides what the DAV:activity-set of the version created by checking in this resource ends up being 🧚
13.4 Additional Workspace Properties 🍓
the activity feature adds one REQUIRED property for a workspace, and it's a good one 👑
13.4.1 DAV:current-activity-set ⭐
this property tells you which activities are currently being performed in this workspace ✨ when a member of the workspace gets checked out and the checkout request doesn't name an activity, the DAV:current-activity-set is what gets used 🫶 this is what lets an activity-unaware client still update a workspace that needs activity tracking, which is so thoughtful 🥺 the DAV:current-activity-set MAY be restricted to identify at most one activity 💅
<!ELEMENT current-activity-set (href*)>13.5 MKACTIVITY Method 🌸
a MKACTIVITY request creates a brand-new activity resource 🧚 a server MAY restrict activity creation to particular collections, but a client can find out where those collections are with a DAV:activity-collection-set OPTIONS request 🗺️
Marshalling:
If a request body is included, it MUST be a DAV:mkactivity XML element.
<!ELEMENT mkactivity ANY>If a response body for a successful request is included, it MUST be a DAV:mkactivity-response XML element.
<!ELEMENT mkactivity-response ANY>The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:resource-must-be-null): A resource MUST NOT exist at the request-URL.
(DAV:activity-location-ok): The request-URL MUST identify a location where an activity can be created.
Postconditions:
(DAV:initialize-activity): A new activity exists at the request-URL. The DAV:resourcetype of the activity MUST be DAV:activity. 🎉
13.5.1 Example - MKACTIVITY 🦋
REQUEST
MKACTIVITY /act/test-23 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cachein this example, a new activity gets created at http://repo.webdav.org/act/test-23 🎀
13.6 DAV:latest-activity-version Report 🔍
this report can be run on a version history to find the latest version that a given activity has selected from that history 🕵️♀️
Marshalling:
The request body MUST be a DAV:latest-activity-version XML element.
<!ELEMENT latest-activity-version (href)>The response body for a successful request MUST be a DAV:latest-activity-version-report XML element.
<!ELEMENT latest-activity-version-report (href)>The DAV:href of the response body MUST identify the version of the given version history that is a member of the DAV:activity-version-set of the given activity and has no descendant that is a member of the DAV:activity-version-set of that activity. 💖
Preconditions:
(DAV:must-be-activity): The DAV:href in the request body MUST identify an activity.
13.7 Additional OPTIONS Semantics 🌈
if the server supports the activity feature, it MUST include "activity" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods 🫶
a DAV:activity-collection-set element MAY be included in the request body to point at collections that may contain activity resources 📍
Additional Marshalling:
If an XML request body is included, it MUST be a DAV:options XML element.
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one
DAV:activity-collection-set element.If an XML response body for a successful request is included, it MUST be a DAV:options-response XML element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one
DAV:activity-collection-set element.
<!ELEMENT activity-collection-set (href*)>If DAV:activity-collection-set is included in the request body, the response body for a successful request MUST contain a DAV:activity-collection-set element identifying collections that may contain activities. An identified collection MAY be the root collection of a tree of collections, all of which may contain activities. Since different servers can control different parts of the URL namespace, different resources on the same host MAY have different DAV:activity-collection-set values. The identified collections MAY be located on different hosts from the resource. 🌍
13.8 Additional DELETE Semantics 💀
Additional Postconditions:
(DAV:delete-activity-reference): If an activity is deleted, any reference to that activity in a DAV:activity-set, DAV:subactivity-set, or DAV:current-activity-set MUST be removed. 🗑️
13.9 Additional MOVE Semantics 🚚
Additional Postconditions:
(DAV:update-checked-out-reference): If a checked-out resource is moved, any reference to that resource in a DAV:activity-checkout-set property MUST be updated to refer to the new location of that resource. 📦
(DAV:update-activity-reference): If the request-URL identifies an activity, any reference to that activity in a DAV:activity-set, DAV:subactivity-set, or DAV:current-activity-set MUST be updated to refer to the new location of that activity. ✨
(DAV:update-workspace-reference): If the request-URL identifies a workspace, any reference to that workspace in a DAV:current-workspace-set property MUST be updated to refer to the new location of that workspace. 🏠
13.10 Additional CHECKOUT Semantics 🎀
a CHECKOUT request MAY specify the DAV:activity-set for the checked-out resource 💅
Additional Marshalling:
<!ELEMENT checkout ANY> ANY value: A sequence of elements with at
most one DAV:activity-set and at most one DAV:unreserved.
<!ELEMENT activity-set (href+ | new)>
<!ELEMENT new EMPTY>
<!ELEMENT unreserved EMPTY>Additional Preconditions:
(DAV:one-checkout-per-activity-per-history): If there is a request activity set, unless DAV:unreserved is specified, another checkout from a version of that version history MUST NOT select an activity in that activity set. 🙅♀️
(DAV:linear-activity): If there is a request activity set, unless DAV:unreserved is specified, the selected version MUST be a descendant of all other versions of that version history that select that activity. 🧵
Additional Postconditions:
(DAV:initialize-activity-set): The DAV:activity-set of the checked-out resource is set as follows:
- If DAV:new is specified as the DAV:activity-set in the request body, then a new activity created by the server is used.
- Otherwise, if activities are specified in the request body, then those activities are used.
- Otherwise, if the version-controlled resource is a member of a workspace and the DAV:current-activity-set of the workspace is set, then those activities are used.
- Otherwise, the DAV:activity-set of the DAV:checked-out version is used.
(DAV:initialize-unreserved): If DAV:unreserved was specified in the request body, then the DAV:unreserved property of the checked-out resource MUST be "true". 🔓
13.10.1 Example - CHECKOUT with an activity 🌸
REQUEST
CHECKOUT /ws/public/foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkout xmlns:D="DAV:">
<D:activity-set>
<D:href>http://repo.webdav.org/act/fix-bug-23</D:href>
</D:activity-set>
</D:checkout>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cachein this example, the CHECKOUT is happening in the http://repo.webdav.org/act/fix-bug-23 activity 🐛✨
13.11 Additional CHECKIN Semantics 🦋
Additional Preconditions:
(DAV:linear-activity): Any version which is in the version history of the checked-out resource and whose DAV:activity-set identifies an activity from the DAV:activity-set of the checked-out resource MUST be an ancestor of the checked-out resource. 🌳
(DAV:atomic-activity-checkin): If the request-URL identifies an activity, the server MAY fail the request if any of the checked-out resources in the DAV:activity-checkout-set of either that activity or any subactivity of that activity cannot be checked in. 🧺
Additional Postconditions:
(DAV:initialize-activity-set): The DAV:activity-set of the new version MUST have been initialized to be the same as the DAV:activity-set of the checked-out resource. 🪞
(DAV:activity-checkin): If the request-URL identified an activity, the server MUST have successfully applied the CHECKIN request to each checked-out resource in the DAV:activity-checkout-set of both that activity and any subactivity of that activity. 🎊
13.12 Additional MERGE Semantics 🧚
if the DAV:source element of the request body identifies an activity, then for each version history containing a version selected by that activity, the latest version selected by that activity is a merge source. Note that the versions selected by an activity are the versions in its DAV:activity-version-set unioned with the versions selected by the activities in its DAV:subactivity-set. 🧩
Additional Marshalling:
<!ELEMENT checkin-activity EMPTY>Additional Postconditions:
(DAV:checkin-activity): If DAV:checkin-activity is specified in the request body, and if the DAV:source element in the request body identifies an activity, a CHECKIN request MUST have been successfully applied to that activity before the merge sources were determined. 💜
14. Version-Controlled-Collection Feature ✨
okay so, when a collection gets put under version control, a version history resource gets created to hold the versions for that collection, just like any other versionable resource 🗂️. And here's the big twist: a collection version only records info about its version-controlled bindings. It's giving "stay in your lane" 💅. That keeps standard versioning semantics intact, because a version of a collection is not supposed to be modifiable 🔒.
The reason it works this way is that a collection version has no members. Instead, it records in its DAV:version-controlled-binding-set property the binding name and version history resource of each version-controlled internal member. That way, changes to the namespace stay separate from changes to content or dead properties 🧹. If a collection version instead held bindings to other versions, making a new version of one resource would force a new version of every collection version that contains it, and activities would get totally entangled 🕸️💀.
Let's see how messy that gets. Say a "feature-12" activity makes a new version of /x/y/a.html. If collection versions held bindings to member versions, you'd need a new version of /x/y to contain it, and then a new version of /x to contain that. Now say a "bugfix-47" activity makes a new version of /x/z/b.html. Again you'd need a new version of /x/z and a new version of /x. But now you can't merge just "bugfix-47" into another workspace without "feature-12" tagging along, because the version of /x that holds the right /x/z/b.html also holds the /x/y/a.html version made for "feature-12" 😭. Storing only the binding name and version history resource of each version-controlled internal member avoids all of that. Changing which version a member selects doesn't need a new collection version, since the new version is still in the same version history. So "feature-12" and "bugfix-47" stay un-entangled 🦋✨.
Here's an example with three version histories: VH14, VH19, and VH24. VH14 holds versions of a collection. The version-controlled collection /x has version V2 of VH14 as its DAV:checked-in version. V2 recorded two version-controlled bindings, one named "a" pointing to VH19 and one named "b" pointing to VH24. That means /x MUST have two version-controlled bindings, one named "a" for the version-controlled resource in VH19 and one named "b" for the version-controlled resource in VH24. Right now, /x/a has V4 of VH19 as its DAV:checked-in version, and /x/b has V8 of VH24 as its DAV:checked-in version 🎀.
VH19
+---------+
| +---+ |
| | |V4 |
| +---+ |
| | |
| | |
| +---+ |
| | |V5 |
VH14 | +---+ |
+---------+ | | |
| +---+ | | | |
a +---+ | | |V1 | | +---+ |
---->| |checked-in=V4 | +---+ | a | | |V6 |
/ +---+ | | ------>| +---+ |
/ | | / | +---------+
+---+ | +---+ |
/x | |checked-in=V2 | | |V2 |
+---+ | +---+ | VH24
\ | | \ | b +---------+
\ b +---+ | | ------>| +---+ |
---->| |checked-in=V8 | +---+ | | | |V7 |
+---+ | | |V3 | | +---+ |
| +---+ | | | |
+---------+ | | |
| +---+ |
| | |V8 |
| +---+ |
| | |
| | |
| +---+ |
| | |V9 |
| +---+ |
+---------+Heads up, bestie 🚨: for any request that modifies a version-controlled binding of a checked-in version-controlled collection (think DELETE, MOVE, COPY), the request MUST fail unless the collection has a DAV:auto-version property that will automatically check it out when it gets modified 🔐.
A version-controlled collection MAY contain both version-controlled and non-version-controlled bindings 🌈. Only the version-controlled ones are under version control, so non-version-controlled bindings can be added or deleted without checking out the collection 🍓.
Also, a collection version only captures a defined subset of the collection's state 🧩. It captures its dead properties and its bindings to version-controlled resources, but not its live properties or its bindings to non-version-controlled resources.
When a server supports the working-resource feature, a client can check out a collection version to create a working collection 🛠️. A version-controlled collection holds bindings to both version-controlled and non-version-controlled resources, but a working collection holds bindings to version history resources and non-version-controlled resources. When a working collection is first set up, it is initialized with bindings to the version history resources named in the DAV:version-controlled-binding-set of the checked-out collection version. Its members can then be deleted or moved to another working collection. Non-version-controlled resources can be added with methods like PUT, COPY, and MKCOL. When the working collection is checked in, a VERSION-CONTROL request is automatically applied to every non-version-controlled member, and each one gets swapped out for its newly created version history. The DAV:version-controlled-binding-set of the new version created by that check-in contains the binding name and version history URL for each member of the working collection 🎉.
14.1. Version-Controlled Collection Properties
A version-controlled collection has all the properties of a collection and of a version-controlled resource 🧺. On top of those, the version-controlled-collection feature adds the following REQUIRED property for a version-controlled collection 💜.
14.1.1. DAV:eclipsed-set (computed)
This property identifies the non-version-controlled internal members of the collection that are currently eclipsing a version-controlled internal member 👀.
!ELEMENT eclipsed-set (binding-name*)>
<!ELEMENT binding-name (#PCDATA)>
PCDATA value: URL segmentHere's the drama 🎭: an UPDATE or MERGE request can give a version-controlled collection a version-controlled internal member that has the same name as an existing non-version-controlled internal member. When that happens, the non-version-controlled internal member takes precedence and is said to "eclipse" the new version-controlled internal member. If the non-version-controlled member gets removed (say, by a DELETE or MOVE), the version-controlled member is exposed again 🌸.
14.2. Collection Version Properties
A collection version has all the properties of a version 🌷. On top of those, the version-controlled-collection feature adds the following REQUIRED property for a collection version 🫶.
14.2.1. DAV:version-controlled-binding-set (protected)
This property captures the name and version history of each version-controlled internal member of a collection 📇.
<!ELEMENT version-controlled-binding-set
(version-controlled-binding*)>
<!ELEMENT version-controlled-binding
(binding-name, version-history)>
<!ELEMENT binding-name (#PCDATA)>
PCDATA value: URL segment
<!ELEMENT version-history (href)>14.3. Additional OPTIONS Semantics
If the server supports the version-controlled-collection feature, it MUST include "version-controlled-collection" as a field in the DAV response header from an OPTIONS request on any resource that supports any versioning properties, reports, or methods 📣.
14.4. Additional DELETE Semantics
Additional Preconditions:
DAV:cannot-modify-checked-in-parent: If the request-URL identifies a version-controlled resource, the DELETE MUST fail when the collection containing that resource is a checked-in version-controlled collection, unless DAV:auto-version semantics will automatically check out that collection 🙅♀️.14.5. Additional MKCOL Semantics
Additional Preconditions:
If the request creates a new resource that gets automatically placed under version control, all preconditions for VERSION-CONTROL apply to the request 🧁.
Additional Postconditions:
If the new collection is automatically put under version control, all postconditions for VERSION-CONTROL apply to the request ✨.
14.6. Additional COPY Semantics
Additional Preconditions:
DAV:cannot-copy-collection-version: If the source of the request is a collection version, the request MUST fail 🚫.14.7. Additional MOVE Semantics
Additional Preconditions:
DAV:cannot-modify-checked-in-parent: If the source of the request is a version-controlled resource, the request MUST fail when the collection containing the source is a checked-in version-controlled collection, unless DAV:auto-version semantics will automatically check out that version-controlled collection 🔒.DAV:cannot-modify-destination-checked-in-parent: If the source of the request is a version-controlled resource, the request MUST fail when the collection containing the destination is a checked-in version-controlled collection, unless DAV:auto-version semantics will automatically check out that version-controlled collection 🛑💖.14.8 Additional VERSION-CONTROL Semantics ✨
okay so VERSION-CONTROL has its own extra rules, and they're giving strict bestie energy 💅
Additional Preconditions:
DAV:cannot-modify-checked-in-parent: if the parent of the request-URL is a checked-in version-controlled collection, the request MUST fail unless DAV:auto-version semantics will automatically check out that version-controlled collection. no sneaking edits into a checked-in parent, that's a hard no 🙅♀️🔒
Additional Postconditions:
DAV:new-version-controlled-collection: if the request body identified a collection version, the collection at the request-URL MUST contain a version-controlled internal member for each DAV:version-controlled-binding listed in the DAV:version-controlled-binding-set of that collection version. the name and DAV:version-history of the internal member MUST be the DAV:binding-name and the DAV:version-history given by that DAV:version-controlled-binding. 🧩 if the internal member is in a workspace and another member of that workspace has the same version history, then those two members MUST identify the same version-controlled resource. otherwise, a VERSION-CONTROL request with a server selected version of the version history MUST have been applied to the URL for that internal member. the server picks the version, not you, periodt 🌸
14.9 Additional CHECKOUT Semantics 🎀
Additional Postconditions:
DAV:initialize-version-history-bindings: if the request has been applied to a collection version, the new working collection MUST be initialized to contain a binding to each of the history resources listed in the DAV:version-controlled-binding-set of that collection version. so the fresh working copy comes pre-loaded with all its history links, iconic 🦋
14.10 Additional CHECKIN Semantics 🌈
Additional Postconditions:
DAV:initialize-version-controlled-bindings: if the request-URL identified a version-controlled collection, then the DAV:version-controlled-binding-set of the new collection version MUST contain a DAV:version-controlled-binding that identifies the binding name and version history for each version-controlled binding of that version-controlled collection. the new version has to remember every single binding, no forgetting 🧠✨
DAV:version-control-working-collection-members: if the request-URL identified a working collection, a VERSION-CONTROL request MUST have been automatically applied to every non-version-controlled member of the working collection, and each non-version-controlled member MUST have been replaced by its newly created version history. 🔄 if a working collection member was a non-version-controlled collection, then every member of that non-version-controlled collection MUST have been placed under version control before the non-version-controlled collection was placed under version control. so the inside goes first, the outside second, that's just good manners 👑 finally, the DAV:version-controlled-binding-set of the new collection version MUST contain a DAV:version-controlled-binding that identifies the binding name and the version history URL for each member of the working collection. everybody gets a listing, no one gets left out 💖
14.11 Additional UPDATE and MERGE Semantics 🍓
Additional Postconditions:
DAV:update-version-controlled-collection-members: if the request modified the DAV:checked-in version of a version-controlled collection, then the version-controlled members of that version-controlled collection MUST have been updated. in particular:
- a version-controlled internal member MUST have been deleted if its version history is not identified by the
DAV:version-controlled-binding-setof the newDAV:checked-inversion. gone, no ghosts left behind 👻 - a version-controlled internal member for a given version history MUST have been renamed if its binding name differs from the
DAV:binding-namefor that version history in theDAV:version-controlled-binding-setof the newDAV:checked-inversion. name glow-up 💅 - a new version-controlled internal member MUST have been created when a version history is identified by the
DAV:version-controlled-binding-setof theDAV:checked-inversion, but there was no member of the version-controlled collection for that version history. if a new version-controlled member is in a workspace that already has a version-controlled resource for that version history, then the new member MUST be just a binding (i.e., another name for) that existing version-controlled resource. otherwise, the content and dead properties of the new version-controlled member MUST have been initialized to be those of the version specified for that version history by the request. if the request doesn't specify a version for that version history, the server defined version is the one that gets picked 🧚
15 Internationalization Considerations 🌸
okay so this spec is built to play nice with the IETF Policy on Character Sets and Languages [RFC2277] 🌍. basically, wherever a human-readable string shows up in the protocol, either its charset is stated outright or XML mechanisms spell it out. and those strings can also say what natural language they're in, which is lowkey amazing 🫶
most of the human-readable strings here live in properties, like DAV:creator-displayname. as RFC 2518 defines, properties get their values marshaled as XML. XML has built-in charset tagging and encoding, and XML processors MUST be able to read at least UTF-8 [RFC2279] encoded XML elements from the ISO 10646 multilingual plane. wait, that's not a requirement here, let me be clear: the text says processors "require" it, so they must read it. the charset parameter of the Content-Type header plus the XML "encoding" attribute give charset info to MIME and XML processors. using the charset header correctly with XML is covered in RFC 3023. XML also does language tagging, so an element can say what language its content is in. XML uses either IANA registered language tags (see RFC 3066) or ISO 639 language tags in the xml:lang attribute to mark the language of an element's content and attributes 🗣️✨
DeltaV apps are built on WebDAV, so they're bound by the internationalization requirements in RFC 2518, Section 16. in short, those requirements call for XML charset tagging, charset encoding, and language tagging 💖. they also strongly recommend reading RFC 3023 for how to use MIME media types for XML transport and the charset header 📚
in this spec, a label is a human-readable string that gets marshaled in the Label header and as XML in request entity bodies. when it's used in the Label header, the label's value is URL-escaped and encoded using UTF-8 🎀
16 Security Considerations 🔐
ok this part is serious, bestie, so pay attention 😭. every security consideration of WebDAV in RFC 2518, Section 17 applies to WebDAV versioning too. some parts of the versioning protocol help with the security risks WebDAV brings, but other parts can make those risks worse. the details are below 👇
16.1 Auditing and Traceability 🕵️♀️
WebDAV makes it so much easier for a remote client to modify resources on a site, but that also means important info can get overwritten and lost, whether by accident or on purpose. WebDAV versioning helps with this by guaranteeing that old info is saved as immutable versions, so it's easy to retrieve or restore 🛟. the version history also logs when changes were made and who made them. when requests are properly authenticated, the history gives a clear audit trail for changes to web resources. that can make it way easier to figure out where a security problem came from, so you can guard against it later 🔍💅
16.2 Increased Need for Access Control 🔑
WebDAV versioning links together lots of related pieces of info. that means an authentication or authorization mistake could let a client find sensitive stuff 😬. for example, if version history isn't protected by access control, a client could look at the version history of a public resource and use it to find later versions the user meant to keep private. so you really need solid authentication and accurate authorization 🛡️
a WebDAV versioning client should be designed to handle a mix of 200 (OK) and 403 (Forbidden) responses when it tries to access the properties and reports a resource supports. for example, a user might be allowed to read the content and dead properties of a version-controlled resource, but not the DAV:checked-in, DAV:checked-out, or DAV:version-history properties of that same resource 🙈
16.3 Security Through Obscurity 🫣
"obscurity" isn't real security, the spec admits that, but it's still a good trick for keeping honest people honest 🤭. in this protocol, version URLs, version history URLs, and working resource URLs are generated by the server and can be obfuscated so they don't draw attention. for example, a version of "http://foobar.com/reviews/salaries.html" might get a URL like "http://foobar.com/repo/4934943" 🧚♀️
16.4 Denial of Service 💀
auto-versioning in WebDAV can create a huge number of resources on the server, since every update to a resource could make a brand new version resource. that raises the risk of a denial of service attack that eats up the server's storage 😱. this risk is especially serious because it can happen by accident, like when an aggressive auto-save feature in an editing client goes wild. a server can lower this risk by using delta storage techniques to keep the cost of extra versions small, and by limiting auto-versioning to a locking client, which cuts down on accidental version creation 🛑💜
17 IANA Considerations 🌷
this document uses the XML element namespace defined by RFC 2518. all the other IANA considerations from RFC 2518 apply to WebDAV Versioning too 📝
18 Intellectual Property ✨
okay bestie, this part is all about who owns what 💅 the IETF is basically saying it takes no position on whether any intellectual property rights might apply to the technology in this document, and it doesn't claim to have checked for any. if you want the rules on rights for standards-track stuff, go look at BCP-11. copies of any claimed rights, assurances of licenses, or results of an attempt to get a general license can be requested from the IETF Secretariat 🧚
the IETF also invites anyone who knows about a copyright, patent, patent application, or other proprietary right that might cover technology needed to practice this standard to tell them. just send it to the IETF Executive Director 🦋
19 Acknowledgements 🫶
this protocol is the group project of the authors and the rest of the DeltaV design team 🌈 the squad is Boris Bokowski, Bruce Cragun (Novell), Jim Doubek (Macromedia), David Durand (INSO), Lisa Dusseault (Xythos), Chuck Fay (FileNet), Yaron Goland, Mark Hale (Interwoven), Henry Harbury (Merant), James Hunt, Jeff McAffer (OTI), Peter Raymond (Merant), Juergen Reuter, Edgar Schwarz (Marconi), Eric Sedlar (Oracle), Bradley Sergeant, Greg Stein, and John Vasta (Rational) 👑
they also want to give a shoutout to the authors of the WebDAV and HTTP protocols, since this one is built right on top of their foundation, plus the super helpful feedback from the WebDAV and DeltaV working groups 💜
20 References 📚
these are the sources this document leans on, so here they are in full:
- [ISO639] ISO, "Code for the representation of names of languages", ISO 639:1988, 1998.
- [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996.
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998.
- [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998.
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen, "HTTP Extensions for Distributed Authoring - WEBDAV", RFC 2518, February 1999.
- [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T.Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
- [RFC3023] Murata, M., St.Laurent, S. and D. Kohn, "XML Media Types", RFC 3023, January 2001.
- [RFC3066] Alvestrand, H., "Tags for the Identification of Languages", BCP 47, RFC 3066, January 2001.
Appendix A - Resource Classification 🎀
this document brings in a bunch of different versioning resources, like version-controlled resources, versions, checked-out resources, and version history resources 🦋 when clients find resources on a server, they might find it useful to sort them into classes, for example to decide which icon or menu options to show in the UI 💅
clients should classify a resource by checking the values of the DAV:supported-method-set (see Section 3.1.3) and DAV:supported-live-property-set (see Section 3.1.4) properties on that resource 🔥
the list below shows the supported live properties and methods for each kind of versioning resource. if an optional feature brings in a new kind of versioning resource, the feature's name is in parentheses after that resource's name. if a live property or method is optional for a kind of versioning resource, the feature that introduces it is in parentheses after the property or method name 🌸
A.1 DeltaV-Compliant Unmapped URL (a URL that identifies no resource)
supported methods:
- PUT [RFC2616]
- MKCOL [RFC2518]
- MKACTIVITY (activity)
- VERSION-CONTROL (workspace)
- MKWORKSPACE (workspace)
A.2 DeltaV-Compliant Resource
supported live properties:
DAV:commentDAV:creator-displaynameDAV:supported-method-setDAV:supported-live-property-setDAV:supported-report-set- all properties defined in WebDAV [RFC2518].
supported methods:
A.3 DeltaV-Compliant Collection
supported live properties:
- all DeltaV-compliant resource properties.
supported methods:
- BASELINE-CONTROL (baseline)
- all DeltaV-compliant resource methods.
A.4 Versionable Resource
supported live properties:
DAV:workspace(workspace)DAV:version-controlled-configuration(baseline)- all DeltaV-compliant resource properties.
supported methods:
- VERSION-CONTROL
- all DeltaV-compliant resource methods.
A.5 Version-Controlled Resource
supported live properties:
DAV:auto-versionDAV:version-history(version-history)DAV:workspace(workspace)DAV:version-controlled-configuration(baseline)- all DeltaV-compliant resource properties.
supported methods:
- VERSION-CONTROL
- MERGE (merge)
- all DeltaV-compliant resource methods.
A.6 Version
supported live properties:
DAV:predecessor-setDAV:successor-setDAV:checkout-setDAV:version-nameDAV:checkout-fork(in-place-checkout or working resource)DAV:checkin-fork(in-place-checkout or working resource)DAV:version-history(version-history)DAV:label-name-set(label)DAV:activity-set(activity)- all DeltaV-compliant resource properties.
supported methods:
- LABEL (label)
- CHECKOUT (working-resource)
- all DeltaV-compliant resource methods.
A.7 Checked-In Version-Controlled Resource
supported live properties:
DAV:checked-in- all version-controlled resource properties.
supported methods:
- CHECKOUT (checkout-in-place)
- UPDATE (update)
- all version-controlled resource methods.
A.8 Checked-Out Resource
supported live properties:
DAV:checked-outDAV:predecessor-setDAV:checkout-fork(in-place-checkout or working resource)DAV:checkin-fork(in-place-checkout or working resource)DAV:merge-set(merge)DAV:auto-merge-set(merge)DAV:unreserved(activity)DAV:activity-set(activity)
supported methods:
- CHECKIN (checkout-in-place or working-resource)
- all DeltaV-compliant resource methods.
A.9 Checked-Out Version-Controlled Resource (checkout-in-place)
supported live properties:
- all version-controlled resource properties.
- all checked-out resource properties.
supported methods:
- UNCHECKOUT
- all version-controlled resource methods.
- all checked-out resource methods.
A.10 Working Resource (working-resource)
supported live properties:
- all DeltaV-compliant resource properties
- all checked-out resource properties
DAV:auto-update.
supported methods:
- all checked-out resource methods.
A.11 Version History (version-history)
supported live properties:
DAV:version-setDAV:root-version- all DeltaV-compliant resource properties.
supported methods:
- all DeltaV-compliant resource methods.
A.12 Workspace (workspace)
supported live properties:
DAV:workspace-checkout-setDAV:baseline-controlled-collection-set(baseline)DAV:current-activity-set(activity)- all DeltaV-compliant collection properties.
supported methods:
- all DeltaV-compliant collection methods.
A.13 Activity (activity)
supported live properties:
DAV:activity-version-setDAV:activity-checkout-setDAV:subactivity-setDAV:current-workspace-set- all DeltaV-compliant resource properties.
supported methods:
- all DeltaV-compliant resource methods.
A.14 Version-Controlled Collection (version-controlled-collection)
supported live properties:
DAV:eclipsed-set- all version-controlled resource properties.
supported methods:
- all version-controlled resource methods.
A.15 Collection Version (version-controlled-collection)
supported live properties:
DAV:version-controlled-binding-set- all version properties.
supported methods:
- all version methods.
A.16 Version-Controlled Configuration (baseline)
supported live properties:
DAV:baseline-controlled-collection- all version-controlled resource properties.
supported methods:
- all version-controlled resource methods.
A.17 Baseline (baseline)
supported live properties:
DAV:baseline-collectionDAV:subbaseline-set- all version properties.
supported methods:
- all version methods.
A.18 Checked-Out Version-Controlled Configuration (baseline)
supported live properties:
DAV:subbaseline-set- all version-controlled configuration properties.
supported methods:
- all version-controlled configuration methods.
Authors' Addresses 🌟
here's where you can find the authors 💖
Geoffrey Clemm
Rational Software
20 Maguire Road, Lexington, MA 02421
EMail: geoffrey.clemm@rational.com
Jim Amsden
IBM
3039 Cornwallis, Research Triangle Park, NC 27709
EMail: jamsden@us.ibm.com
Tim Ellison
IBM
Hursley Park, Winchester, UK S021 2JN
EMail: tim_ellison@uk.ibm.com
Christopher Kaler
Microsoft
One Microsoft Way, Redmond, WA 90852
EMail: ckaler@microsoft.com
Jim Whitehead
UC Santa Cruz, Dept. of Computer Science
1156 High Street, Santa Cruz, CA 95064
EMail: ejw@cse.ucsc.eduFull Copyright Statement 💖
Copyright (C) The Internet Society (2002). All Rights Reserved. 🎀
okay so the Internet Society holds the copyright here, and honestly it's giving generous 🦋. You're allowed to copy this document and share it with others. You can also write derivative works that comment on or explain it, or that help people implement it, and you can publish and distribute those in whole or in part with no restriction of any kind ✨. The one catch is that the copyright notice and this paragraph have to be included on every copy and every derivative work 🫶.
BUT the document itself can't be modified in any way. That means no removing the copyright notice or the references to the Internet Society or other Internet organizations 🙈. There are two exceptions. The first is developing Internet standards, where the copyright procedures in the Internet Standards process must be followed. The second is translating it into languages other than English 🌈.
The limited permissions above are perpetual, and the Internet Society or its successors or assigns will never revoke them 👑.
This document and the information in it is provided on an "AS IS" basis, and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE 💅.
Acknowledgement 🌸
Funding for the RFC Editor function is currently provided by the Internet Society 🧚.
📦 where this page comes from
- ietf: rfc3253 2002-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms