Scope Check

A scope check assesses how well a manuscript fits a journal's scope and returns ranked alternative journals. This page is the integration contract for the scope check: the request ChronosHub sends to a partner, and the response the partner must return.

A partner implements a single endpoint that accepts the request and returns the response. Both messages are JSON. The schemas below are JSON Schema (draft 2020-12).

This contract describes the check payloads only — not the transport-level concerns (endpoint URL, authentication) which are agreed per partner during onboarding.

Request (ChronosHub → partner)

ChronosHub sends the manuscript details plus the filters configured for the requesting customer. At least one filter id is always present.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ScopeCheckRequest",
  "type": "object",
  "additionalProperties": false,
  "required": ["journal", "title", "customer", "filters"],
  "properties": {
    "journal": {
      "type": "string",
      "description": "ISSN of the journal the manuscript was submitted to.",
      "pattern": "^\\d{4}-\\d{3}[\\dXx]$"
    },
    "title": {
      "type": "string",
      "description": "Manuscript title.",
      "minLength": 1
    },
    "abstract": {
      "type": ["string", "null"],
      "description": "Manuscript abstract. May be null or omitted when not available."
    },
    "customer": {
      "type": "string",
      "description": "Identifier of the ChronosHub customer the check is run for.",
      "minLength": 1
    },
    "filters": {
      "type": "object",
      "additionalProperties": false,
      "required": ["filterIds"],
      "description": "Partner-defined filters to apply to the check, configured per customer.",
      "properties": {
        "filterIds": {
          "type": "array",
          "description": "One or more partner filter identifiers. Always at least one.",
          "minItems": 1,
          "items": { "type": "string", "minLength": 1 }
        }
      }
    }
  }
}

Example

{
  "journal": "1520-5126",
  "title": "Visible-Light Photoredox Catalysis in the Enantioselective Synthesis of Complex Natural Products",
  "abstract": "We report a general strategy for the enantioselective construction of quaternary stereocenters using a dual photoredox/organocatalytic manifold.",
  "customer": "ACS",
  "filters": {
    "filterIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
  }
}

Response (partner → ChronosHub)

The partner returns a message, the selected (submitted-to) journal with a scope verdict, and a list of ranked journal matches.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ScopeCheckResponse",
  "type": "object",
  "required": ["message", "data"],
  "properties": {
    "message": {
      "type": "string",
      "description": "Human-readable summary of the check outcome."
    },
    "data": {
      "type": "object",
      "required": ["selected_journal", "ranked_matches"],
      "properties": {
        "selected_journal": {
          "type": "object",
          "required": ["issn", "name", "in_scope", "score", "explanation"],
          "description": "The journal the manuscript was submitted to, with its scope verdict.",
          "properties": {
            "issn": { "type": "string" },
            "name": { "type": "string" },
            "in_scope": {
              "type": "boolean",
              "description": "Whether the manuscript is in scope for this journal."
            },
            "score": {
              "type": "number",
              "description": "Fit score for this journal."
            },
            "explanation": {
              "type": "string",
              "description": "Rationale for the verdict."
            }
          }
        },
        "ranked_matches": {
          "type": "array",
          "description": "Alternative journals ranked by fit, best first.",
          "items": {
            "type": "object",
            "required": ["rank", "issn", "name", "score"],
            "properties": {
              "rank": {
                "type": "integer",
                "description": "1-based rank; 1 is the best match."
              },
              "issn": { "type": "string" },
              "name": { "type": "string" },
              "score": {
                "type": "number",
                "description": "Fit score for this match."
              },
              "relevant_articles": {
                "type": ["array", "null"],
                "description": "Representative articles from this journal. May be null or omitted.",
                "items": {
                  "type": "object",
                  "required": ["id", "title"],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Stable identifier for the article (e.g. an OpenAlex URL)."
                    },
                    "title": { "type": "string" },
                    "year": {
                      "type": ["integer", "null"],
                      "description": "Publication year, or null when unknown."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Example

{
  "message": "Scope check completed successfully",
  "data": {
    "selected_journal": {
      "issn": "1573-3432",
      "name": "Journal of Autism and Developmental Disorders",
      "in_scope": true,
      "score": 87.4,
      "explanation": "This paper aligns with the journal's recurring focus areas."
    },
    "ranked_matches": [
      {
        "rank": 1,
        "issn": "1939-3806",
        "name": "Autism Research",
        "score": 94.2,
        "relevant_articles": [
          {
            "id": "https://openalex.org/W3132230678",
            "title": "Technology-Assisted Emotion Recognition",
            "year": null
          }
        ]
      },
      {
        "rank": 2,
        "issn": "1573-3432",
        "name": "Journal of Autism and Developmental Disorders",
        "score": 87
      }
    ]
  }
}

Notes

• All property names are case-sensitive. The response uses snake_case; the request uses camelCase.
• abstract (request) and relevant_articles / year (response) are the only optional/nullable fields; everything else is required.
• Scores are plain JSON numbers; no fixed range or precision is assumed by ChronosHub.
• A partner failure, a malformed body, or a response missing required fields causes the check to be recorded as failed on the ChronosHub side; it does not corrupt the manuscript's record.