Configuration Block Specification

All SA configuration blocks are HTML <script>elements with a specific structure.

Here's an example;

<script type="application/sa+json" handler="handler-name" name="my-name">
{
  "@context": "https://attr.sygnal.com",
  "@version": "0.1",
  ... 
}
</script>

The script tag supports has 3 defined attributes;

type = application/sa+json

Identifies the script MIME type as an SA configuration block.

SA6 will support Sygnal's HSON data format natively as well, with the application/sa+hson type.

• Type

• Name

• Handler

Here's an example;

<script type="application/sa+json" handler="handler-name" name="my-name">
{
  "@context": "https://attr.sygnal.com",
  "@version": "0.1",
  "url": "https://conversion-tracker-url.com", 
  "transactionIdType": "query", 
  "transactionId": "transactionId",
  "type": "contact",
  "item": ""  
}
</script>

Engineer's Technical Notes

We've designed SA's Configuration Blocks protocol with a number of primary considerations.

Standards compliance;

• Conventional HTML <script> mechanics are used

  • Scripts are never rendered as page content

  • The MIME type ensures that it is not confused with regular scripts

• Conventional JSON standards are supported

Script efficiency;

• SA library scripts can easily locate relevant configuration blocks

  • Explicit types can be found by matching the handler name; script[handler="handler-name" i]

  • And/or the handler categories; script[handler="handler-name" i], script[handler^="handler-name." i]

  • Where possible these handler names are case-insensitive

• Configuration blocks can also be identified by specific name

Convenience

• Where possible, case-insensitive value matches script[handler="handler-name" i]

Extensibility & future proofing;

'script[handler="foo" i], script[handler^="foo." i]'

e.g. a typical Basin Contact Us form

<script type="application/sa+json">
{
  "@context": "https://attr.sygnal.com",
  "@type": "ConversionEvent",
  "@version": "0.1",
  "url": "https://conversion-tracker-url.com", 
  "transactionIdType": "query", 
  "transactionId": "transactionId",
  "type": "contact",
  "item": ""  
}
</script>

• Data pulled in from session var

• Overridden with data here

• TransactionID created / set

Make these easier to find

<script type="application/sa5+json" handler="ConversionEvent">
{
  "@context": "https://attr.sygnal.com",
  "@type": "ConversionEvent",
  "@version": "0.1",
  "url": "https://conversion-tracker-url.com", 
  "transactionIdType": "query", 
  "transactionId": "transactionId",
  "type": "contact",
  "item": ""  
}
</script>

Decisions

@context

@type

@version

<script type="application/sa+json" handler="Trigger.Timer">
{
  "@context": "https://attr.sygnal.com",
  "@type": "TimerTrigger",
  "@version": "0.1",
  "timer": "60", 
  "timerRepeat": "120",
  "event": "my-event" 
}
</script>

<script type="application/sa+json" handler="Event" name=""> 
{
  "@context": "https://attr.sygnal.com",
  "@type": "TimerTrigger",
  "@version": "0.1",
  "timer": "60", 
  "timerRepeat": "120",
  "event": "my-event" 
}
</script>

? change @type to @handler

? is there value to context and type?

SEO?

Docs?

Make these easier to find

<script type="application/sa5+json" handler="ConversionEvent">
{
  "@context": "https://attr.sygnal.com",
  "@type": "ConversionEvent",
  "@version": "0.1",
  "url": "https://conversion-tracker-url.com", 
  "transactionIdType": "query", 
  "transactionId": "transactionId",
  "type": "contact",
  "item": ""  
}
</script>

Named Config Blocks

Used when referenced from a :config modifier on a base attribute.

<script type="application/sa5+json" name="foo">
{
  "@context": "https://attr.sygnal.com",
  "@type": "ConversionEvent",
  "@version": "0.1",
  "url": "https://conversion-tracker-url.com", 
  "transactionIdType": "query", 
  "transactionId": "transactionId",
  "type": "contact",
  "item": ""  
}
</script>

• name added

Supported Data Formats

• JSON

• HSON ( coming soon )

Approach Notes

We're moving towards a precedent set by JSON-LD, as it's cleaner and more utilitarian.

About the MIME Type

In general, we'll stick with standard conventions;

The type of application/sa+json follows conventions like JSON-LD, which is `application

application/sa+json

application/sa+hson

Legacy

application/sa5+json

application/sa5+hson

• application/:

  • The primary type (application) represents a general type of data. It’s often used for data that doesn't fall under other primary types such as text, image, audio, etc.

  • application/ typically indicates that the content is not intended to be directly displayed to the user but rather used or processed by an application. For example, application/json, application/xml, and application/pdf indicate that the content is primarily intended for programmatic use.

• sa5+json:

  • The +json suffix tells the system that the content is in JSON format and should be handled as such. It helps parsers and applications recognize how to process the content.

  • The sa5 is a custom subtype, giving a specific indication about what the JSON content represents in the context of your system.