Canonical transaction paths

I propose to start using new syntax for addressing transactions compiled from the blueprint in hooks instead of transaction names. Transaction names will be supported for backward compatibility.

Transaction names were historically intended only as bread crubs — a human readable location of the specific transaction in the blueprint. Transaction name was never meant as a canonical transaction identifier and that’s the reason for its terrible indeterminism.

Format will be a concatenation/serialization of the origin object:

• Use colon : character as a delimiter
• Colon character in API Name, Resource Name, Resource Group Name, Action Name or Example Name will be escaed with backslash
• Examples are identified by string "Example " + its index in array starting from 1 (not 0)

Possible questions:

• Omit leading "Example " string and use zero indexed position?
• Use different delimiter?
• Use delimiter string at the beginning of the path?
• Does term “Canonical transaction path” make sense?

Examples

1. Full notation with multiple request-response pairs

# Some API Name

## Group Some Group Name

### Some Resource Name [/resource]

#### Some Action [GET]

+ Request (application/json)
+ Response 200(application/json)

+ Request (application/xml)
+ Response 200 (application/xml)

Transaction origin object:

{
  "apiName": "Some API Name",
  "resourceGroupName": "Some Group Name",
  "resourceName": "Some Resource Name",
  "actionName": "Some Action Name",
  "exampleName": "Example 2"
}

Compiled canonical path:

Some API Name:Some Group Name:Some Resource Name:Some Action Name:Example 2

2. Full notation without group

# Some API Name

### Some Resource Name [/resource]

#### Some Action [GET]

+ Request (application/json)
+ Response 200 (application/json)

Transaction origin object:

{
  "apiName": "Some API Name",
  "resourceGroupName": "",
  "resourceName": "Some Resource Name",
  "actionName": "Some Action Name",
  "exampleName": "Example 1"
}

Compiled canonical path:

Some API Name::Some Resource Name:Some Action Name:Example 1

3. Full notation without group and API name

### Some Resource Name [/resource]

#### Some Action [GET]

+ Request (application/json)
+ Response 200 (application/json)

Transaction origin object:

{
  "apiName": "",
  "resourceGroupName": "",
  "resourceName": "Some Resource Name",
  "actionName": "Some Action Name",
  "exampleName": "Example 1"
}

Compiled canonical path:

::Some Resource Name:Some Action Name:Example 1

4. Simplified notation

# GET /message
+ Response 200 (text/plain)

      Hello World

Transaction origin object:

{
  "apiName": "",
  "resourceGroupName": "",
  "resourceName": "/message",
  "actionName": "GET",
  "exampleName": "Example 1"
}

Compiled canonical path:

::/message:GET:Example 1

[honzajavorek]

@halfvector We had some design sessions around this in April and per my last comment I have a better idea on how it should work. Currently there’s no ETA though. It needs finalization of the design before anyone can implement it. I recognize it as one of the largest Dredd pain points, but as such it also requires me to carve out a significant block of uninterrupted time to tackle it.

[honzajavorek]

@halfvector Not really at this moment. We decided to focus on reviving and fixing the heart of Dredd’s validation, Gavel. Let’s see what we’re up to after that.