feat: add markdown to JSON parser enhancements (label normalization + schema validation)

[Praneel7015]

Addresses Issue #18.

1. Added use of jsonschema and made it used maintainer.schema.json as its schema

checks if jsonschema is present on system

try:
    import jsonschema
    HAS_JSONSCHEMA = True
except ImportError:
    HAS_JSONSCHEMA = False

2. Added Label Normalization and Valid label as per the schema and checks validation

# Mapping of user input labels to schema-valid labels
LABEL_NORMALIZATION = {
    # Lowercase variants
    "github": "GitHub",
    "gitlab": "GitLab",
    "codeberg": "Codeberg",
    "bitbucket": "BitBucket",
    "linkedin": "LinkedIn",
    "mastodon": "Mastodon",
    "bluesky": "BlueSky",
    "substack": "Substack",
    "discourse": "Discourse",
    "twitter": "Twitter",
    "email": "Email",
    "rss": "RSS",
    "web": "Web",
    "x": "X",
    # Mixed case variants
    "Github": "GitHub",
    "Gitlab": "GitLab",
    "Linkedin": "LinkedIn",
    "Bluesky": "BlueSky",
    "Bitbucket": "BitBucket",
    # Common aliases
    "Website": "Web",
    "website": "Web",
    "Blog": "Web",
    "blog": "Web",
    "Mail": "Email",
    "mail": "Email",
    "X/Twitter": "X",
    "Twitter/X": "X",
}

# Valid labels as per schema
VALID_LABELS = {
    "GitHub", "GitLab", "Gitlab", "Codeberg", "BitBucket", "LinkedIn",
    "X", "Twitter", "Mastodon", "Bluesky", "BlueSky", "Substack",
    "Discourse", "Email", "RSS", "Web"
}

loading and validation

def load_schema():
    """Load the JSON schema for validation."""
    schema_path = Path(__file__).parent / "maintainer.schema.json"
    if not schema_path.exists():
        return None
    with open(schema_path, encoding="utf-8") as f:
        return json.load(f)


def validate_data(data: dict, schema: dict) -> list[str]:
    """Validate data against schema. Returns list of errors."""
    if not HAS_JSONSCHEMA:
        return []

    errors = []
    validator = jsonschema.Draft7Validator(schema, format_checker=jsonschema.FormatChecker())
    for error in validator.iter_errors(data):
        path = ".".join(str(p) for p in error.absolute_path) if error.absolute_path else "(root)"
        errors.append(f"  {path}: {error.message}")
    return errors

3. If an user produces a label not in VALID_LABELS, prints a stderr warning so the submitter/maintainer sees it early

normalized_label = normalize_label(label.strip())
if normalized_label not in VALID_LABELS:
    print(f"Warning: Unknown or invalid social label '{label.strip()}' (normalized: '{normalized_label}')", file=sys.stderr)

4. Added Miscellaneous Improvements such as following:

• adds trailing newline when writing JSON
• Added --validate flag handling in main
• Inserted a warning print when parsing socials for unknown labels.
  PS : this is still a draft to check if all conditions are being met and if the issue is resolved with this

This is just the start, expect more to come :)

[idlip]

Hey praneel, thanks alot for working on this feature.

• Looks useful to automate and scale in future.

Actually, I was thinking if we should change the workflow of adding maintainers.
Still intervention is required to make PR and merge

I'll experiment with this thoroughly (idk when)

[Praneel7015]

Sounds good, let me know if you have/face any issues with this

[agriyakhetarpal]

Hi @Praneel7015, thanks for asking for my review on this PR. I am not a maintainer for this project, and I don't work for FOSS United either (I'm happy to help nevertheless), so I'll leave it to Dilip to guide you through the rest of this PR and to review it in more detail beyond my initial skim through the code. Thanks for your work! Some comments below:

[agriyakhetarpal]

Since the schema file is available next to this file, will there be a case where it won't be found? I think this check would be redundant.

[Praneel7015]

Now that i think about it, you're right. i dont think there will be a case where that occurs

[agriyakhetarpal]

Overall, I think this file is redundant, as it reimplements functionality already available for use via JSON schema checkers, as I mentioned in the original issue description: #18 (comment). Not to say this is bad, but it's probably better to rely on existing, tested tools, which are less prone to bugs. Maybe it's easier to let people fix any errors instead of auto-fixing entries?

[Praneel7015]

Makes Sense, my thoughts were having it automated will be easier for all 😅, but you are also right its basically just redundant file which does the same thing as what the JSON schema checker would do.
will look into removing it!