Normative description of "YOLO format"

[dmyersturnbull]

Search before asking

• I have searched https://github.com/ultralytics/docs/issues and did not find a similar request.

Description

See this forum question. Multiple docs describe the "YOLO format" and its data.yaml (or dota8.yaml, etc.), including:

• https://docs.ultralytics.com/platform/quickstart/#yolo-dataset-structure
• https://docs.ultralytics.com/platform/data/datasets/#what-label-formats-are-supported
• https://docs.ultralytics.com/datasets/obb/#yolo-obb-format
• https://docs.ultralytics.com/datasets/segment/#dataset-yaml-format

Some docs also contradict each other. Moreover, these are mostly example-driven; the exact requirements aren't stated clearly, at least not where I was able to find readily. For example, which keys are required? What can the YAML file be named? Is path: sub/path supported? Is it images/train or train/images?

A simple, normative description would be helpful -- natural-language text, a JSON Schema, both, or anything else.

See also ultralytics/ultralytics#23747

Use case

This would have been very helpful when I was trying to diagnose a problem I was having with uploads (in the linked forum post). I'm thinking a lot of existing documentation could also be removed (replaced with a link to the dedicated doc) for easier reading and maintenance.

Additional

No response

Are you willing to submit a PR?

• Yes I'd like to help by submitting a PR!

[UltralyticsAssistant]

👋 Hello @dmyersturnbull, thank you for submitting a ultralytics/docs 🚀 issue! This is an automated response to help us triage quickly, and an Ultralytics engineer will also assist you soon 🔎

To help us address this efficiently, please ensure the following details are included:

1. For bug reports:

• A clear and concise description of the bug
• A minimum reproducible example MRE that demonstrates the issue
• Your environment details (OS, Python version, package versions)
• Expected behavior vs. actual behavior
• Any error messages or logs related to the issue

2. For feature requests:

• A clear and concise description of the proposed feature
• The problem this feature would solve
• Any alternative solutions you've considered

3. For questions:

• Provide as much context as possible about your question
• Include any research you've already done on the topic
• Specify which parts of the documentation, if any, you've already consulted

Since this appears to be a docs/feature-style request, thank you also for offering to submit a PR 🙌 Please add any implementation ideas or draft scope directly in this thread so maintainers can align with you quickly.

Please make sure you've searched existing issues to avoid duplicates. If you need to add any additional information, please comment on this issue.

[pderrenger]

You’re right that we should have a single, normative “YOLO dataset YAML” spec in the docs; today the source-of-truth is the loader code, where train and val (or validation, auto-renamed) are required and you must provide either names or nc (with consistency checks), while path and split entries can be relative/absolute and are resolved to full paths—see the check_det_dataset reference and how the YAML is discovered/validated via find_dataset_yaml; if you’re up for a PR, a dedicated spec page (optionally with a JSON Schema) derived from these rules would be ideal and we’re happy to review.