KLIQ|Developers

Grading Schemas

A grading schema defines the attributes that are measured during an inspection and how they combine into an overall score. Each schema belongs to a vertical and can be linked to one or more catalog types.

Attribute types

TypeDescriptionExample
scaleNumeric range with stepPSA 1–10, NEN 2767 1–6
rangeContinuous numeric value with unitDiamond carat weight (0.01–100 ct)
enumFixed list of named optionsWatch condition (Mint, Excellent, …)
letter_gradeOrdered letter gradesGIA color D–Z, GIA clarity FL–I3

Overall formulas

MethodBehaviour
weighted_averageΣ (attributeValue × weight) / Σ weight
minimumLowest sub-grade wins (Sheldon coin scale)
minimum_then_averageBGS: lowest sub-grade is the cap, average is the display
pass_throughSub-grades reported individually, no single score (GIA 4Cs)

Listing schemas for a vertical

GET/v1/verticals/{slug}/grading-schemasList grading schemas for a vertical
GET/v1/grading-schemas/{id}Get a schema with its attributes
import { KliqClient } from '@kliq-ai/sdk';

const kliq = new KliqClient({ apiKey: process.env.KLIQ_API_KEY! });

const schemas = await kliq.gradingSchemas.listForVertical('collector-scan');

for (const s of schemas.data) {
  console.log(s.slug, '-', s.name);
}
// psa-10-point        - PSA 10-Point Grading Scale
// bgs-10-point        - BGS/Beckett 10-Point Grading Scale
// gia-diamond-4c      - GIA Diamond 4Cs
// gia-colored-gem     - GIA Colored Stone Grading
// sheldon-coin-scale  - Sheldon 70-Point Coin Grading Scale
// watch-condition     - Watch Condition Grading
// wine-bottle-condition - Wine Bottle Condition Grading

// Fetch a specific schema with attributes
const psa = await kliq.gradingSchemas.get('psa-10-point');

for (const attr of psa.attributes) {
  console.log(`${attr.key} (weight: ${attr.weight}) — ${attr.type}`);
}
// centering (weight: 0.25) — scale
// corners   (weight: 0.25) — scale
// edges     (weight: 0.25) — scale
// surface   (weight: 0.25) — scale

PSA grading schema example

The PSA 10-point schema uses four scale attributes (1–10, step 1) combined with a weighted_average formula. Equal weights mean the overall grade is the arithmetic mean of all four sub-grades.

const psa = await kliq.gradingSchemas.get('psa-10-point');

console.log(psa.overallFormula);
// { method: 'weighted_average', weightField: 'weight' }

console.log(psa.attributes[0]);
// {
//   key: 'centering',
//   name: 'Centering',
//   type: 'scale',
//   config: { min: 1, max: 10, step: 1 },
//   weight: 0.25,
//   required: true
// }

Creating a custom schema

const schema = await kliq.gradingSchemas.create('t_abc123', {
  verticalSlug: 'wine-scan',
  slug: 'parker-100-point',
  name: 'Parker 100-Point Wine Scale',
  standard: 'Robert Parker / Wine Advocate',
  overallFormula: { method: 'weighted_average', weightField: 'weight' },
  attributes: [
    {
      key: 'color',
      name: 'Color & Appearance',
      type: 'scale',
      config: { min: 0, max: 5, step: 1 },
      weight: 0.05,
      required: true,
    },
    {
      key: 'aroma',
      name: 'Aroma & Bouquet',
      type: 'scale',
      config: { min: 0, max: 15, step: 1 },
      weight: 0.15,
      required: true,
    },
    {
      key: 'flavor',
      name: 'Flavor & Finish',
      type: 'scale',
      config: { min: 0, max: 20, step: 1 },
      weight: 0.2,
      required: true,
    },
    {
      key: 'overall_quality',
      name: 'Overall Quality & Potential',
      type: 'scale',
      config: { min: 0, max: 10, step: 1 },
      weight: 0.1,
      required: true,
    },
  ],
});

console.log(schema.id); // "schema_def456"

Re-use public schemas where possible

Public schemas like psa-10-point or nen-2767-condition are already linked to catalog types and come with grading guides. Only create a custom schema when no public standard fits your use case.

Next steps