Specification

The Specification field is a flexible extension point available on both Schema and Property documents. It enables developers to attach additional metadata in a standardized format that can be used for custom logic in UI field editors, source code generation, or other tooling integrations.

Overview

The Specification field stores a string formatted using the application/x-www-form-urlencoded standard (commonly referred to as URLSearchParams format). It contains key-value pairs separated by ampersands (&), where each key and value are URL-encoded.

For example:

icon=table&group=Combat

Use Cases

The Specification field is commonly used for:

  • Schema metadata: Define an icon, group behavior, or UI preferences:

    icon=table&category=Gameplay&hideInMenu=true

  • Property editor extensions: Pass configuration values to custom editors:

    colorFormat=RGB&alpha=true

  • Source code generation: Customize how types or methods are generated:

    typeName=MyEnum&csAttribute=Obsolete

Encoding Guide

All keys and values must be properly URL-encoded to ensure compatibility with parsing libraries and avoid format-breaking characters.

### Encoding in JavaScript

In any browser console or Node.js REPL:

const params = new URLSearchParams({
  icon: "sword",
  group: "Items and Stuff",
  noThumbnail: true
});
console.log(params.toString());
// Output: icon=sword&group=Items%20and%20Stuff&noThumbnail=true

### Encoding in Excel

To encode values manually using Excel formulas:

  • Build a key-value pair:

    =ENCODEURL("noThumbnail") & "=" & ENCODEURL("true")

  • Combine multiple:

    =ENCODEURL("icon") & "=" & ENCODEURL("sword") & "&" & ENCODEURL("group") & "=" & ENCODEURL("Items and Stuff")

Best Practices

  • Use lowercase or camelCase for keys to ensure consistency.

  • Avoid spaces or special characters in keys; values should always be encoded.

See also