schema: improved docs