Proposal: Add `custom` field support for extensibility

[mikeschinkel]

The JSON Resume schema serves a diverse community with varying needs. Many users have requested additions to the schema for their specific use cases – from tracking certification expiration dates to adding academic teaching experience, from including language proficiency standards to extending work highlights with additional metadata. While each request has merit for specific users, adding fields for every specialized need would make the schema increasingly complex and harder to maintain.

This proposal suggests a flexible solution: adding an optional custom field to every object in JSON Resume, including the root object. This approach would allow users to extend their resumes with implementation-specific data while maintaining compatibility with existing tools. Users could address their unique requirements immediately through custom fields, while the core schema remains focused on widely-used fields that serve the majority of users.

For example, academic institutions could add teaching-specific fields to work entries, certification authorities could include renewal requirements, and language schools could add proficiency standards – all without requiring changes to the core schema. This flexibility would enable innovation and experimentation while ensuring that resumes remain compatible across the JSON Resume ecosystem.

How it works

Resume authors would be able to add a custom object to any object in their resume to store additional properties. For example, adding detailed certification information:

{
  "certificates": [{
    "name": "AWS Solutions Architect",
    "issuer": "Amazon Web Services",
    "date": "2023-01-15",
    "custom": {
      "expiryDate": "2026-01-15",
      "licenseNumber": "AWS-123456",
      "credentialVerificationUrl": "https://aws.amazon.com/verify/AWS-123456"
    }
  }],
  "custom": {
    "lastUpdated": "2024-02-11",
    "templateVersion": "2.4.1",
    "generatedBy": "ResumeBuilder Pro"
  }
}

Or adding company-specific information to a work entry:

{
  "work": [{
    "company": "Tech Corp",
    "position": "Senior Developer",
    "startDate": "2020-01-01",
    "custom": {
      "teamSize": 12,
      "budgetResponsibility": "$1.2M",
      "directReports": 5,
      "performanceRating": "Exceeds Expectations"
    }
  }]
}

The custom field can be added to any object in the resume, including the root object and all nested objects:

{
  "basics": {
    "name": "John Doe",
    "custom": {
      "pronouns": "they/them",
      "timeZone": "America/Los_Angeles",
      "personalityAssessments": {
        "MBTI": "INTJ",
        "DiSC": "C/S"
      }
    }
  },
  "education": [{
    "institution": "University of Science",
    "area": "Computer Science",
    "studyType": "Bachelor",
    "custom": {
      "gpa": 3.8,
      "honors": "magna cum laude",
      "thesisTitle": "Applications of Machine Learning in Climate Science",
      "academicAdvisor": "Dr. Jane Smith"
    }
  }]
}

Extending Array Fields

The custom field can also elegantly handle metadata for array fields like keywords and highlights. Instead of modifying these arrays to accept objects (which would break existing tooling), metadata can be stored in the parent object's custom field:

{
  "skills": [{
    "name": "Web Development",
    "keywords": ["javascript", "python", "react"],
    "custom": {
      "keywords": {
        "python": {
          "proficiency": "expert",
          "yearsOfExperience": 5,
          "certifications": ["PCEP", "PCAP"]
        },
        "javascript": {
          "proficiency": "advanced",
          "preferredFramework": "Vue.js"
        }
      }
    }
  }],
  "work": [{
    "company": "Tech Corp",
    "highlights": [
      "Led team of 5 developers",
      "Increased performance by 50%"
    ],
    "custom": {
      "highlights": [
        {
          "highlightPrefix":"Led",
          "impact": "high",
          "category": "leadership",
          "verifiableOutcome": true
        },
        {
          "highlightPrefix":"Increased",
          "metrics": ["latency", "throughput"],
          "timeframe": "6 months",
          "documentation": "Q2 2023 Performance Report"
        }
      ]
    }
  }]
}

This approach maintains compatibility with existing tools that expect simple string arrays while allowing rich metadata to be associated with each array item.

Common Use Cases

This extension mechanism supports many real-world needs:

• Adding industry-specific certifications and qualifications
• Including internal company information for HR systems
• Supporting region-specific requirements (like Chinese personal identifiers or European Union GDPR preferences)
• Enabling integration with applicant tracking systems
• Adding metadata for automated processing
• Supporting experimental features before they become part of the standard schema

Schema Implementation

To implement this proposal, the schema would need to be modified to allow a custom field in every object, including the root level. Here's how the schema changes would look:

{
  "definitions": {
    "custom": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "custom": { "$ref": "#/definitions/custom" },
    "basics": {
      "type": "object",
      "properties": {
        "custom": { "$ref": "#/definitions/custom" },
        "location": {
          "type": "object",
          "properties": {
            "custom": { "$ref": "#/definitions/custom" }
          }
        }
      }
    },
    "work": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "custom": { "$ref": "#/definitions/custom" }
        }
      }
    }
    // ... similar changes for other objects
  }
}

This schema change:

• Defines a reusable custom field definition
• Adds the custom field to every object in the schema
• Maintains backward compatibility since the field is optional
• Allows any valid JSON in the custom object through additionalProperties: true

Benefits

This approach provides several key advantages:

1. Complete backward compatibility with existing tools and theme formatters
2. A standardized way to extend any object in the schema
3. Flexibility to support various use cases without bloating schema
4. Gradual adoption path - the custom field is entirely optional
5. Clear separation between standard fields and custom fields
6. Reduced maintenance burden, as specialized fields needed by a small subset of users can be implemented through custom properties rather than requiring schema changes
7. Natural evolution path for the schema, as maintainers can analyze commonly used custom fields across resumes to identify which properties merit inclusion in future versions of the standard schema

Would love to hear the community's thoughts on this approach and any suggestions for refinement.

[mikeschinkel]

I will be happy to add a PR if you are willing to accept this.

[HoneyNutz]

I strongly support the direction of this recommendation. Having tried to extend the schema myself with varying custom fields, I've found the current structure lacks the necessary flexibility.

While the existing meta field provides a mechanism, its location requires significant effort on the user side to map custom data back to relevant entities (like specific work experiences), making it impractical for many use cases.

The being said, I understand the concern about preventing schema bloat and complexity from too many optional fields catering to niche uses. But given the current limitations on extensibility this recommendation seemingly appears to offer a much-needed, balanced and structured approach to resolving prescriptive structure elements and complexities in customization with the current structure.

[thomasdavis]

Thanks for the fleshed out issue. I'm happy to just go ahead with it.

And throughout the documentation, I think it would be nice to just add as a secondary concept than primary e.g. on the homepage schema example, it should just be in the commentary, not in the example

[dev-dull]

Since JSON does not support comments, custom would help fill this gap.

edit: this feature is a blocker to my adoption of the schema

[cculbreath]

This proposal addresses a significant short-coming of the existing schema. What's needed to move forward with this?