r3ply Schemas#

This page is a listing of all the schemas used by r3ply so they can be browsed or referenced by tooling.

#

Table of Contents

──𓆝𓆟𓆞𓆝𓆟 𓆝𓆟𓆞──

Site Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/site.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "r3ply site config",
  "description": "Used to configure the r3ply commenting system.",
  "": "See https://r3ply.com/docs for more info.",
  "type": "object",
  "required": [],
  "unevaluatedProperties": false,
  "properties": {
    "version": {
      "title": "r3ply version",
      "description": "Declares what version of r3ply this config conforms to.",
      "type": "string",
      "enum": [
        "0.0.1"
      ],
      "default": "0.0.1"
    },
    "enabled": {
      "title": "Enable r3ply",
      "description": "False completely turns off r3ply, including any downstream processes.",
      "type": "boolean",
      "default": true
    },
    "site": {
      "title": "New site configuration",
      "description": "Declares a new site this config applies to, consisting of domain x r3ply service, and signet. See docs for more info.",
      "type": "array",
      "items": {
        "": "https://r3ply.com/schemas/v0.0.1/config/signet.v0.0.1.json"
      },
      "default": []
    },
    "comments": {
      "": "https://r3ply.com/schemas/v0.0.1/config/comments.v0.0.1.json"
    },
    "moderation": {
      "": "https://r3ply.com/schemas/v0.0.1/config/moderation.v0.0.1.json"
    },
    "extra": {
      "": "https://r3ply.com/schemas/v0.0.1/config/extra.v0.0.1.json"
    }
  }
}

Signet Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/signet.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "": "signet",
  "title": "Site information",
  "description": "Requires a separate entry for each `site` x `r3ply` (and `issued`) combination.",
  "type": "object",
  "required": [
    "domain",
    "r3ply",
    "signet",
    "issued"
  ],
  "properties": {
    "domain": {
      "title": "Site domain",
      "description": "The domain that this configuration applies to. Hostname only.",
      "type": "string",
      "format": "hostname"
    },
    "r3ply": {
      "title": "r3ply domain",
      "description": "The r3ply app to receive comments from. Hostname only.",
      "type": "string",
      "format": "hostname"
    },
    "signet": {
      "title": "Signet data",
      "description": "The r3ply-issued signet key.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{22}$",
      "examples": [
        "qhQ6YSUvQNLb1lCdw3kDRg"
      ],
      "": "See docs/overview#sites-signets."
    },
    "issued": {
      "title": "Issue date (of signet)",
      "description": "Used as a key identifier, e.g. for signet rotations and versioning of signet key.",
      "type": "string",
      "format": "date",
      "examples": [
        "2025-08-22"
      ]
    },
    "label": {
      "title": "Site label",
      "description": "A human readable label of a site. Useful for filtering further downstream.",
      "": "See also `filter*`.",
      "type": "string",
      "pattern": "^[\\s\\S]+$",
      "maxLength": 256,
      "examples": [
        "test",
        "test #1",
        "production",
        "website"
      ]
    },
    "extra": {
      "": "https://r3ply.com/schemas/v0.0.1/config/extra.v0.0.1.json"
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "domain": "site.local.test",
      "r3ply": "cli.r3ply.test",
      "signet": "J9cDuB3tBit3WDGQmvbCIw",
      "issued": "2025-08-20"
    },
    {
      "domain": "spenc.es",
      "r3ply": "r3ply.com",
      "signet": "qhQ6YSUvQNLb1lCdw3kDRg",
      "issued": "2025-08-22"
    }
  ]
}

Comments Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/comments.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "Comments config",
  "description": "Control top-level commenting parameters.",
  "": "See also `comments.email`.",
  "type": "object",
  "required": [],
  "additionalProperties": false,
  "properties": {
    "enabled": {
      "title": "Enable comments",
      "description": "False completely turns off commenting.",
      "type": "boolean",
      "default": true
    },
    "paths*": {
      "title": "Site paths",
      "type": "array",
      "description": "Specifies which path to allow comments on. The \"paths*\" name means glob patterns can be used.",
      "items": {
        "type": "string",
        "pattern": "^[\\s\\S]*$"
      },
      "examples": [
        "/**",
        "!/private"
      ],
      "": "glob patterns can be used"
    },
    "cache": {
      "title": "Cache pending comments",
      "description": "Can be temporarily fetched, e.g. via front end javascript.",
      "type": "boolean",
      "default": false,
      "": "the pending comments cache is very unstable still. TODO: some kind of basic, automatic moderation to flag for spam. TODO: document better exactly how much time the cache makes comments available (72 hours is reasonable)."
    },
    "md_to_html": {
      "title": "Markdown to HTML conversion",
      "description": "Converts markdown syntax to HTML tags.",
      "type": "boolean",
      "default": true,
      "": "See also `sanitize_html`. TODO: remove this config variable. If people don't want MD -> HTML conversion they can just not use the converted HTML."
    },
    "sanitize_html": {
      "title": "Sanitize HTML",
      "description": "Nothing from the outside world should be trusted, especially HTML in comments. Only disable this if you reall know what you're doing.",
      "type": "boolean",
      "default": true,
      "": "See also `allow_tags`."
    },
    "allow_tags": {
      "title": "HTML Tags to allow",
      "description": "Only tags listed here will be allowed by the HTML sanitizer.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\s\\S]*$"
      },
      "default": [
        "a",
        "br",
        "p",
        "span",
        "strong",
        "s",
        "del",
        "em",
        "u",
        "ul",
        "ol",
        "li",
        "blockquote",
        "hr",
        "code",
        "pre",
        "table",
        "tr",
        "td",
        "th",
        "caption",
        "thead",
        "tbody",
        "tfoot",
        "kbd",
        "mark",
        "sub",
        "small"
      ],
      "examples": [
        [
          "a",
          "br",
          "p",
          "span",
          "strong",
          "s",
          "del",
          "em",
          "u",
          "ul",
          "ol",
          "li",
          "blockquote",
          "hr",
          "code",
          "pre",
          "table",
          "tr",
          "td",
          "th",
          "caption",
          "thead",
          "tbody",
          "tfoot",
          "kbd",
          "mark",
          "sub",
          "small"
        ]
      ]
    },
    "email": {
      "": "https://r3ply.com/schemas/v0.0.1/config/comments/email.v0.0.1.json"
    },
    "": {
      "const": [
        "email"
      ],
      "default": [
        "email"
      ],
      "": "TODO: remove this. There are better ways to derive this."
    }
  }
}

Email (comment source) Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/comments/email.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "Emailed comments config",
  "description": "Control parameters unique to email.",
  "type": "object",
  "required": [],
  "additionalProperties": false,
  "properties": {
    "enabled": {
      "title": "Enable email comments",
      "description": "False disables email comments only.",
      "type": "boolean",
      "default": true,
      "": "See `comments.enabled`."
    },
    "filter*": {
      "title": "Filter site",
      "description": "Specifies which sites (by label) will be processed.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\s\\S]*$"
      },
      "default": [
        "**"
      ],
      "examples": [
        "*",
        "!local"
      ],
      "": "See `label` property on `site` config variable."
    },
    "email_signature_separator": {
      "title": "Email signature separator",
      "description": "Text boundary that appears before email signature.",
      "type": "string",
      "pattern": "^[\\s\\S]*$",
      "default": "\n",
      "examples": [
        "﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍\nWrite your comment above 👆\n\nDON'T alter the subject line ⚠️\n\nEverything below this line 👇 will be ignored\n﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍﹍"
      ],
      "": "This should be the same string you use in the `body` field of your mailto links. It's a good idea to use some recognizable text. You can also put instructions to the commenter in here."
    },
    "attachments": {
      "title": "Allow attachments",
      "description": "Attachments are currently disabled but support will be added in the future.",
      "type": "boolean",
      "default": false,
      "const": false
    },
    "max_size_bytes": {
      "title": "Max size (in bytes)",
      "description": "If an email comment exceeds either this amount or the limit set upstream by the r3ply server it will be rejected.",
      "type": "integer",
      "minimum": 0,
      "default": 1048576,
      "": "i.e. 1 MB."
    },
    "block*": {
      "title": "Block list",
      "description": "Specifies which pseudyonym/email address to block.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\s\\S]*$"
      },
      "default": [],
      "examples": [
        "e8a20d6*",
        "[email protected]",
        "*@spam.com"
      ]
    },
    "comment_{}": {
      "title": "Comment template (string)",
      "description": "Specifies how email comments should be transformed into text. Default is a stringified JSON object.",
      "type": "string",
      "pattern": "^[\\s\\S]*$",
      "": "For longer comment templates see `&comment_{}`."
    },
    "&comment_{}": {
      "title": "Comment template (file)",
      "description": "Specifies how email comments should be transformed into text. Must be a path.",
      "type": "string",
      "format": "uri-reference",
      "examples": [
        "./viaEmail/comment.html",
        "/example.comment.template.md",
        "../comment.txt"
      ],
      "": "See also `comment_{}`."
    },
    "comment_mime": {
      "title": "Comment mime type",
      "description": "It can be at times useful to specify the mime type of a comment file.",
      "type": "string",
      "pattern": "^[\\S]*$",
      "maxLength": 128,
      "default": "text/plain"
    }
  }
}

Moderation Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/moderation.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "Moderation config",
  "description": "Control the various moderation channels",
  "": "i.e. what should happen to comment after they've been processed.",
  "type": "object",
  "definitions": {
    "options": {
      "title": "Moderation options",
      "description": "Shared options across all moderation channels",
      "type": "object",
      "required": [],
      "properties": {
        "enabled": {
          "title": "Enable moderation",
          "description": "False completely turns off moderation for this channel.",
          "type": "boolean",
          "default": true,
          "": "See `moderation.enabled`."
        },
        "allow*": {
          "title": "Allow list",
          "description": "Plain text email or pseudonym bypassing moderation.",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[\\s\\S]*$",
            "maxLength": 256
          },
          "default": [],
          "examples": [
            "*@alice.com",
            "[email protected]"
          ]
        },
        "comments": {
          "title": "Comment sources",
          "description": "Specify which commenting sources to allow for this moderation channel.",
          "type": "array",
          "items": {
            "enum": [
              "email"
            ]
          }
        },
        "filter*": {
          "title": "Filter site",
          "description": "Specifies which sites (by label) will be processed.",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[\\s\\S]*$"
          },
          "examples": [
            "*",
            "!local"
          ]
        }
      }
    }
  },
  "required": [],
  "unevaluatedProperties": false,
  "properties": {
    "enabled": {
      "title": "Enable moderation",
      "description": "False completely disables moderation.",
      "type": "boolean",
      "default": true
    },
    "github": {
      "type": "array",
      "items": {
        "": "https://r3ply.com/schemas/v0.0.1/config/moderation/github.v0.0.1.json"
      },
      "maxItems": 2,
      "default": []
    },
    "webhook": {
      "type": "array",
      "items": {
        "": "https://r3ply.com/schemas/v0.0.1/config/moderation/webhook.v0.0.1.json"
      },
      "maxItems": 5,
      "default": []
    },
    "local": {
      "type": "array",
      "items": {
        "": "https://r3ply.com/schemas/v0.0.1/config/moderation/local.v0.0.1.json"
      },
      "default": []
    }
  }
}

Github Moderation Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/moderation/github.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "Github moderation",
  "description": "Specify how comments should be sent to GitHub for moderation.",
  "type": "object",
  "required": [
    "owner",
    "repo",
    "file_path_{}"
  ],
  "unevaluatedProperties": false,
  "allOf": [
    {
      "": "https://r3ply.com/schemas/v0.0.1/config/moderation.v0.0.1.json#/definitions/options"
    }
  ],
  "properties": {
    "type": {
      "const": "github"
    },
    "owner": {
      "title": "Repo owner",
      "description": "This should be the user or org name.",
      "type": "string",
      "pattern": "^[\\S]+$",
      "maxLength": 1024,
      "examples": [
        "asimpletune",
        "r3ply"
      ]
    },
    "repo": {
      "title": "Repo name",
      "description": "Name of GitHub repository.",
      "type": "string",
      "pattern": "^[\\S]+$",
      "maxLength": 1024,
      "examples": [
        "yoursite"
      ]
    },
    "file_path_{}": {
      "title": "File path template (string)",
      "description": "Specifies the file path of the new comment.",
      "type": "string",
      "pattern": "^(?!\\s*/)[\\s\\S]*$",
      "maxLength": 1024,
      "examples": [
        "content/comments/{{ comment.id | slice(end=8) }}.md"
      ],
      "": "Can never begin with a `/`."
    },
    "base_branch_{}": {
      "title": "Base branch template (string)",
      "description": "Specifies the base branch of the new comment, e.g. `main`.",
      "type": "string",
      "pattern": "^[\\s\\S]*$",
      "maxLength": 128,
      "default": "main"
    },
    "head_branch_{}": {
      "title": "Head branch template (string)",
      "description": "Specifies the head branch of the new comment, e.g. `comment-123`.",
      "type": "string",
      "pattern": "^[\\s\\S]*$",
      "maxLength": 256,
      "default": "comment-{{ comment.ts_rcvd }}-{{ comment.id[:8] }}.md",
      "examples": [
        "{{ comment.id[:8] }}-{{ comment.ts_rcvd }}"
      ]
    },
    "commit_msg_{}": {
      "title": "Commit message template (string)",
      "description": "Specifies the commit message of the new comment.",
      "type": "string",
      "pattern": "^[\\s\\S]*$",
      "maxLength": 2096,
      "default": "\"commit_msg_{}\" = \"\"\"Comment submitted:\n\n  - Sender: {{ author.pseudonym }}\n  - Timestamp: {{ comment.ts_rcvd }}\n  - Subject: {{ comment.subject.url }}\n\n> {{ comment.txt | split(pat=\"\r\n\") | join(sep=\"\n> \") }}\"\"\""
    },
    "&commit_msg_{}": {
      "title": "Commit message template (file)",
      "description": "Specifies a file that has the commit message of the new comment.",
      "type": "string",
      "format": "uri-reference"
    },
    "pr_title_{}": {
      "title": "PR title template (string)",
      "description": "Specifies the PR title of the new comment.",
      "type": "string",
      "pattern": "^[\\s\\S]*$",
      "maxLength": 1024,
      "default": "New comment ({{ comment.id[:8] }}) on {{ comment.subject.url }} by author `{{ author.pseudonym[:7] }}`"
    },
    "pr_body_{}": {
      "title": "PR body template (string)",
      "description": "Specifies the PR body of the new comment.",
      "type": "string",
      "pattern": "^[\\s\\S]*$",
      "maxLength": 2096,
      "default": ""
    },
    "&pr_body_{}": {
      "title": "PR body template (file)",
      "description": "Specifies a file containing the PR body of the new comment.",
      "type": "string",
      "format": "uri-reference",
      "": "File reference."
    },
    "github_host": {
      "title": "Github host",
      "description": "Only useful for enterprise instances of GitHub.",
      "type": "string",
      "format": "hostname",
      "default": "github.com",
      "": "You probable don't want to change this."
    }
  }
}

Local Moderation Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/moderation/local.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "Local moderation",
  "description": "Specifies a moderation channel used locally.",
  "": "This is usually used by `re` the r3ply CLI tool.",
  "type": "object",
  "required": [
    "file_path_{}"
  ],
  "unevaluatedProperties": false,
  "allOf": [
    {
      "": "https://r3ply.com/schemas/v0.0.1/config/moderation.v0.0.1.json#/definitions/options"
    }
  ],
  "properties": {
    "type": {
      "const": "local"
    },
    "file_path_{}": {
      "title": "File path template (string)",
      "description": "Specifies the file path of the new comment.",
      "type": "string",
      "pattern": "^(?!\\s*/)[\\s\\S]*$",
      "maxLength": 1024,
      "examples": [
        "content/comments/{{ comment.id | slice(end=8) }}.md"
      ],
      "": "Can never begin with a `/`."
    }
  }
}

Webhook Moderation Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/moderation/webhook.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "Webhook moderation",
  "description": "Specifies how comments should be sent to a webhook.",
  "": "Note: webhook moderation is useful taking custom actions.",
  "type": "object",
  "required": [
    "url"
  ],
  "unevaluatedProperties": false,
  "allOf": [
    {
      "": "https://r3ply.com/schemas/v0.0.1/config/moderation.v0.0.1.json#/definitions/options"
    }
  ],
  "properties": {
    "type": {
      "const": "webhook"
    },
    "url": {
      "title": "Webhook URL",
      "description": "The comment will be in the request body.",
      "type": "string",
      "format": "uri",
      "": "TODO: when r3ply supports secrets allow secrets to be stored here."
    },
    "method": {
      "title": "Webhook method",
      "description": "The method the comment will be sent with.",
      "type": "string",
      "enum": [
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "default": "POST"
    }
  }
}

Extra Config#

link

{
  "": "https://r3ply.com/schemas/v0.0.1/config/extra.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "Extra config",
  "description": "An area for user's to define extra configuration.",
  "type": "object",
  "required": [],
  "additionalProperties": {
    "type": [
      "string",
      "number",
      "boolean",
      "null"
    ],
    "pattern": "^[\\s\\S]*$"
  },
  "propertyNames": {
    "pattern": "^[\\s\\S]*$"
  }
}

System Config#

link

(I.e. for running a r3ply app)

{
  "": "https://r3ply.com/schemas/v0.0.1/config/r3ply.v0.0.1.json",
  "": "http://json-schema.org/draft-04/schema#",
  "title": "r3ply system config",
  "description": "Used to configure a system that provides r3ply commenting functionality.",
  "": "See https://r3ply.com/docs for more info.",
  "type": "object",
  "required": [
    "domains"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "title": "r3ply version",
      "description": "Declares what version of r3ply this config conforms to.",
      "type": "string",
      "enum": [
        "0.0.1"
      ],
      "default": "0.0.1"
    },
    "domains": {
      "title": "r3ply domains",
      "description": "The domains that configuration applies to. Hostname only.",
      "type": "array",
      "items": [
        {
          "type": "string",
          "format": "hostname"
        }
      ],
      "additionalItems": {
        "type": "string",
        "format": "hostname"
      },
      "minItems": 1,
      "examples": [
        [
          "r3ply.com",
          "test.r3ply.com"
        ],
        [
          "your-r3ply-app.com"
        ]
      ],
      "": "must match the domain that serves the config"
    },
    "enabled": {
      "title": "Enable r3ply",
      "description": "False completely turns off r3ply, including any downstream processes.",
      "type": "boolean",
      "default": true,
      "": "⚠️: if disabled, downstream sites will be affected."
    },
    "sites*": {
      "title": "Allowed sites",
      "description": "Specifies what sites to accepts comments on behalf of.",
      "": "If undefined then all sites are allowed.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[\\S]*$",
        "maxLength": 128
      }
    },
    "admin": {
      "type": "array",
      "title": "Admin",
      "description": "Contact list for r3ply system admins.",
      "minItems": 1,
      "maxItems": 99,
      "uniqueItems": true,
      "items": {
        "description": "a name + email pair of each admin",
        "type": "object",
        "required": [
          "name",
          "email"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "description": "human readble name of the admin",
            "type": "string",
            "pattern": "^[\\s\\S]*$",
            "examples": [
              "Guybrush Threepwood"
            ]
          },
          "email": {
            "description": "the email of the admin",
            "type": "string",
            "format": "email",
            "examples": [
              "[email protected]"
            ],
            "": "Do not use mailbox format, e.g. \"Le Chuck GP <[email protected]>\""
          }
        }
      }
    },
    "email": {
      "title": "Email processing",
      "description": "Configure parameters related to processing comments via email for sites.",
      "type": "object",
      "required": [],
      "additionalProperties": false,
      "default": {
        "enabled": true,
        "attachments": false,
        "max_size_bytes": 5242880
      },
      "properties": {
        "enabled": {
          "title": "Enable email comments",
          "description": "If false, all emails are ignored.",
          "type": "boolean",
          "default": true,
          "": "⚠️: if disabled, downstream sites will be affected."
        },
        "max_size_bytes": {
          "title": "Max size (bytes)",
          "description": "Emails are ignored if their size (in bytes) exceed the min(system, site) configs",
          "type": "number",
          "default": 5242880,
          "": "i.e. 5 MB.",
          "minimum": 0
        },
        "attachments": {
          "title": "Email attachments",
          "description": "Attachments are currently disabled but support will be added in the future.",
          "const": false
        }
      }
    }
  }
}

Comments (0) #

Comment [+] Expand

Pending Comments (0)